owlen/agents-2025-10-23.md

fix(config): align ollama cloud defaults with current api host ✅

• Severity: High – older defaults used the non-canonical base host and bespoke env var, forcing manual tweaks before cloud requests succeeded (crates/owlen-core/src/config.rs, config.toml, docs/configuration.md).
• Resolution (2025-10-23): Canonical base URL now defaults to https://ollama.com per the latest Ollama Cloud REST guide, with automatic normalisation of https://api.ollama.com as a legacy alias. Configuration templating, CLI/TUI helpers, and generated docs reference the vendor-provided OLLAMA_API_KEY, while still accepting OLLAMA_CLOUD_API_KEY and OWLEN_OLLAMA_CLOUD_API_KEY with a one-time warning.
• Verification: Added unit coverage for base URL normalisation, adjusted config/env migration tests, and re-ran cargo test -p owlen-core -p owlen-providers to confirm env fallbacks continue to work.

fix(provider/ollama): keep stream whitespace intact

• Severity: High – generate_stream trims every line so assistants lose leading newlines and indentation (crates/owlen-providers/src/ollama/shared.rs:135 and :161).
• Issue: Markdown blocks and code fences arrive malformed, forcing the UI to patch formatting after the fact.
• Plan: Replace the naive trim() with CR/LF stripping that preserves user-visible whitespace, keep incomplete line fragments buffered, and add defensive logging around JSON decode failures.
• Acceptance Criteria: Streaming chunks can start with whitespace (code blocks render correctly); end-of-stream metadata still lands in the final message; no regressions for local or cloud daemons.
• Test Notes: Add unit tests that feed \r\n-terminated chunks with leading spaces, plus an integration test using recorded samples.json; run cargo test -p owlen-providers.

feat(provider/ollama): wire tool calling and response metadata

• Severity: High – Ollama models never see tool descriptors because prepare_chat_request drops them and supports_tools is hard-coded false (crates/owlen-core/src/providers/ollama.rs:825 and :1258).
• Issue: The agent pipeline cannot hand off web.search or other tools; chat stalls when the model requests a function call.
• Plan: Send tool schemas to Ollama, surface tool_call deltas back into ChatResponse, mark capable models as tool-ready, and ensure session handling replays tool results before resuming generation.
• Acceptance Criteria: Models that emit tool calls loop through the MCP tool registry without manual intervention; disabling tools blanks them out; streaming transcripts keep tool boundaries.
• Test Notes: Add provider tests covering tool_calls frames, extend session streaming tests with mock tool responses, and run cargo test -p owlen-core.

feat(usage): track cloud token quotas and expose :limits

• Severity: Medium – there is no hourly/weekly accounting or :limits command even though the UI promises it (crates/owlen-core/src/session.rs, crates/owlen-tui/src/chat_app.rs:6880 area, crates/owlen-tui/src/ui.rs:2280 area).
• Issue: Users cannot see or cap consumption, and the header lacks the cloud usage line from the spec.
• Plan: Introduce a persisted usage ledger (rolling hour/week windows) keyed by provider, surface quotas from config, add :limits to the palette, and render an extra header row with colored percentages plus 80%/95% toasts.
• Acceptance Criteria: Usage survives restart, :limits prints hourly and weekly tallies, header updates after each completion, and quota breaches raise a toast once per band.
• Test Notes: Write time-travel unit tests for the tracker, snapshot the new header rendering, add a TUI command test, and run cargo test -p owlen-core -p owlen-tui.

feat(tool/web): route searches through provider and gate on cloud availability

• Severity: High – web_search hits DuckDuckGo directly (crates/owlen-core/src/tools/web_search.rs:14) and the registry exposes it even when the cloud provider is disabled (crates/owlen-core/src/session.rs:245 range).
• Issue: In restricted environments the tool fails silently, and the model keeps saying it lacks internet access despite the stated goal.
• Plan: Replace the DuckDuckGo client with a provider-aware adapter that calls the configured cloud search endpoint, hide the tool unless the active provider advertises web search support, and surface clean errors for 401/429 responses.
• Acceptance Criteria: With a valid cloud key the assistant auto-invokes web.search; without cloud access the tool is absent and the model does not ask for it; detailed errors reach the toast system.
• Test Notes: Add Wiremock-backed integration tests for happy path, 401, and 429; assert tool registration toggles via session tests; run cargo test -p owlen-core --tests tools.

feat(ui): modernize chat chrome and usage surfacing

• Severity: Medium – the current TUI still uses heavy bordered blocks and text badges (crates/owlen-tui/src/ui.rs:200 onward) and lacks the cockpit-style progress bars requested for context and usage.
• Issue: Visual hierarchy is dated, the context badge is text-only, and screenshots (images/layout.png) no longer match the roadmap.
• Plan: Refresh the header with gradient bars for context and cloud usage, adopt lighter glassmorphism-inspired panels, tighten spacing, update themes, and regenerate screenshots for docs.
• Acceptance Criteria: Header shows context and usage bars with color thresholds, panels use the new styling without breaking vim keybinds, and updated screenshots appear in docs.
• Test Notes: Update golden snapshot tests for the layout, add UI smoke tests for narrow terminals, and capture new PNGs via the existing screenshot script.

docs(release): prep v0.2 guidance and config samples

• Severity: Medium – public docs still advertise v0.1.11 and outdated setup steps (README.md:6, docs/troubleshooting.md, AGENTS.md samples out of sync with actual config schema).
• Issue: Users follow stale instructions, miss new keys (hourly/weekly quotas), and cannot reconcile the config example with generated files.
• Plan: Bump version strings to v0.2, document the new config sections (quotas, list TTL), add troubleshooting for cloud auth and rate limits, and note the revised env naming.
• Acceptance Criteria: README, docs, and sample configs match the implemented features; upgrade notes explain migration steps; release checklist reflects the new DoD.
• Test Notes: Run link checker over docs/, lint Markdown with cargo xtask lint-docs, and have CI confirm the changelog entry.

feat(commands): expose :web on|off toggle in both TUI and CLI

• Severity: Medium – there is no runtime switch for the web-search tool (crates/owlen-tui/src/commands/registry.rs, crates/owlen-tui/src/chat_app.rs), so users must hand-edit config to disable remote lookups when on metered links.
• Issue: Lack of a fast toggle contradicts the DoD requirement for obvious tooling controls and encourages unsafe defaults when privacy-sensitive users need a local-only session.
• Plan: Add :web on|off and owlen providers web --enable/--disable commands that mutate config.tools.web_search.enabled, broadcast the change to active sessions, and synchronise the header indicator/toast copy.
• Acceptance Criteria: Toggling via command takes effect immediately (tool descriptors disappear/appear for the next request), the setting persists to disk, and both CLI+TUI help list the new flags.
• Test Notes: Extend command registry unit tests, add an integration test that toggles and asserts tool exposure, and validate persistence with a temporary config dir.

feat(config): align generated config with provider sections & env fallbacks

• Severity: Medium – the sample config.toml and README snippets still use flat [providers.ollama_cloud] keys with api_key_env = "OLLAMA_CLOUD_API_KEY" and base URL https://ollama.com (config.toml:16, README.md:119), diverging from crates/owlen-core/src/config.rs.
• Issue: Onboarding breaks because the UI and doctor expect the [providers.ollama_cloud] schema with OLLAMA_API_KEY as the default (while warning on legacy names), so fresh installs require manual correction.
• Plan: Regenerate the CLI templated config, update documentation snippets, implement migration warnings for the legacy env name, and ensure doctor explains both env vars with precedence.
• Acceptance Criteria: owlen config init writes the new schema, doctor reports actionable guidance when the legacy env is present, and README/config docs match the generated file.
• Test Notes: Snapshot regeneration output, add config migration tests covering legacy envs, and run cargo test -p owlen-core config suite.

refactor(errors): typed provider failures mapped to structured toasts

• Severity: High – the TUI currently inspects error strings for "429" / "rate limit" substrings (crates/owlen-tui/src/chat_app.rs:10377) and loses context when providers change wording.
• Issue: String matching misses localized messages and risks leaking raw responses into the UI, preventing reliable recovery and localisation.
• Plan: Introduce a typed error enum in owlen-core (Error::Unauthorized, ::RateLimited, ::Unavailable, etc.), propagate it through providers, and map the variants to toast/banners with deterministic copy.
• Acceptance Criteria: Cloud 401/429 cases surface the new typed variants, the UI no longer string-parses errors, logs redact secrets, and analytics tests assert the mapping.
• Test Notes: Extend provider unit tests for HTTP status translation, add UI tests that inject each error variant, and fuzz unknown error text to ensure graceful fallback.

test(integration): cover local/cloud/search tool happy and unhappy paths

• Severity: Medium – there are no Wiremock-backed integration cases validating multi-provider flows; regressions slip through (crates/owlen-core/tests lacks HTTP stubs).
• Issue: Streaming/tool-call regressions and auth handling bugs reach users because only unit tests exist.
• Plan: Create integration tests that spin up stub servers for /api/tags, /api/chat, and /v1/web/search, covering 200/401/429 responses, tool-call loops, and rate-limit recovery.
• Acceptance Criteria: CI runs the new suite, failures are deterministic, and each scenario asserts provider status transitions plus persisted usage updates.
• Test Notes: Use wiremock for HTTP stubbing, reuse sample transcripts from samples.json, and document the fixtures under tests/fixtures/.

chore(deps/ui): upgrade to Ratatui 0.29+ and enable gradient widgets

• Severity: Medium – we pin ratatui = 0.28 and crossterm = 0.28 (Cargo.toml), missing gradient fills, flexible layout APIs, and native mouse handling released in 2025.
• Issue: Without the newer widgets we hand-roll gradients/badges and duplicate layout math, increasing maintenance debt.
• Plan: Bump Ratatui/Crossterm, adopt the Gauge gradient support for context/usage bars, replace custom layout helpers with the new Flex API, and ensure theme palettes cover extended colour spaces.
• Acceptance Criteria: Build succeeds with the upgraded stack, header widgets use the new gradient gauges, and CI snapshots reflect the refreshed rendering.
• Test Notes: Run cargo test -p owlen-tui, update golden snapshots, and manually verify mouse/resize handling in the demo app.

chore(release): bump workspace metadata to v0.2

• Severity: Medium – the workspace version, crates, and README badges still say 0.1.11 (Cargo.toml, README.md:8), undermining the v0.2 delivery narrative.
• Issue: Packaging scripts (AUR, PKGBUILD) and CLI --version output disagree with the roadmap, confusing users and automated installers.
• Plan: Update [workspace.package].version, propagate the bump to crate manifests, adjust badges/screenshots, and refresh packaging metadata (PKGBUILD, docs/CHANGELOG).
• Acceptance Criteria: owlen --version prints 0.2.0, README badges align, and release notes enumerate the v0.2 features.
• Test Notes: Run cargo xtask lint-release, build the Arch package locally, and smoke-test binary version output.