odysseus/ROADMAP.md

# Roadmap / Help Wanted

Odysseus is an evolving self-hosted AI workspace. This roadmap highlights the areas where improvements and contributions are most useful.

It describes current direction, not a fixed release schedule or a complete issue backlog. Specific implementations should be coordinated through existing issues and pull requests.

Contributions target `dev`. The `main` branch is curated for releases.

## Stabilization and reliability

Reliable operation across installations, platforms, providers, and supported hardware remains a priority.

- **CI and validation:** Improve the reliability of automated checks, exact-revision validation, and release confidence. See #5932 and the confirmed docs-only CI regression, #7109.
- **Test quality:** Continue improving deterministic tests, isolation, focused execution, and maintainable test structure. See #2523 and the [testing standard](tests/TESTING_STANDARD.md).
- **Fresh installations:** Expand smoke-test coverage for native Linux, macOS, Windows, WSL, and Docker. Verify clean startup, health reporting, and graceful handling of unavailable optional services. See #3968.
- **Cookbook reliability:** Improve model installation, dependency management, hardware detection, and serving across supported platforms, GPUs, drivers, and execution backends.
- **Email integration:** Resolve remaining Google OAuth regressions, preserve account isolation, and improve cross-provider reliability. See #5637.
- **Storage integrity:** Investigate upload payloads, database growth, indexing, and file lifecycle without introducing unsafe or destructive cleanup. See #4889.
- **Security:** Continue hardening authorization, agent tool execution, prompt-injection boundaries, filesystem access, and handling of untrusted content.
- **Integration diagnostics:** Verify provider and optional-service behavior, improve failure reporting, and ensure unavailable dependencies degrade predictably.

Current stabilization work is coordinated through the [Stabilization & Modularization milestone](https://github.com/odysseus-dev/odysseus/milestone/1).

## Modularization and maintainability

The goal is to make the codebase easier to navigate, test, review, and extend while preserving existing behavior and compatibility.

The initial CSS extraction and substantial tool-domain decomposition have established a foundation, but responsibility boundaries still need improvement.

Current areas of interest:

- **Frontend:** Continue focused decomposition of large document, gallery, settings, calendar, and other UI modules.
- **CSS:** The former `static/style.css` has been split into ordered files under `static/css/`. Improve maintainability without inadvertently changing cascade order, theme behavior, or responsive layouts.
- **Tools:** Continue clarifying ownership within `src/agent_tools/` and related implementations while preserving existing public contracts and compatibility.
- **Backend:** Identify safe boundaries in large Cookbook routes, persistence modules, and feature-specific route handlers.
- **Tests:** Keep test helpers, fixtures, and focused test ownership aligned with the implementation modules they exercise.
- **UI infrastructure:** Reduce duplicated tour scaffolding, fragile modal/window positioning, stale feature flags, and cross-feature coupling.

[#4071](https://github.com/odysseus-dev/odysseus/issues/4071) is the canonical coordination tracker for this work.

Larger PRs can be appropriate for a single coherent decomposition when splitting the work into many smaller PRs would create unnecessary integration complexity. Coordinate the intended boundary before implementation and provide meaningful regression and runtime validation.

### Agent runtime and Harness V2

Harness V2 is under active development.

The agent runtime, including `src/agent_loop.py` and closely related execution, authorization, orchestration, and context contracts, is temporarily frozen for unrelated changes while that work is developed and validated.

Agent-runtime refactors must be coordinated with maintainers. Urgent bug and security reports remain welcome.

This restriction does not apply to unrelated application modules.

## AI, local models, and research

The following improvements remain areas of product interest. Their exact implementations and priority relative to one another require normal issue triage and product decisions.

- **Smaller-model agent efficiency:** Reduce unnecessary prompt, tool-schema, skill, memory, and document context overhead. Improve tool selection and behavior with constrained context windows.
- **Cookbook SGLang support:** Improve setup and serving across relevant operating systems, hardware, and deployment methods.
- **Model discovery and ranking:** Recommend appropriate models using architecture, quantization, RAM/VRAM availability, backend support, multimodal requirements, and expected serving reliability.
- **Deep Research presets:** Explore hardware-appropriate model and parameter configurations for smaller and larger local systems.
- **Cookbook diagnostics:** Expose actionable installation, download, preflight, and serving failures with useful, copyable logs.
- **Speculative decoding:** Investigate supported draft-model configurations for compatible local backends. Evaluate end-to-end correctness and time to successful output, not throughput alone.
- **Provider setup and probing:** Improve integration quality for supported local and hosted providers, including endpoint discovery and capability handling.

## Frontend and user experience

- Improve document and file editing, window behavior, save/export flows, and image-editing reliability.
- Expand agent-assisted workflows for Notes and Todos, including reading, updating, summarizing, and turning information into actionable tasks.
- Improve the mobile gallery and editor experience.
- Strengthen keyboard navigation, accessibility, focus behavior, contrast, and reduced-motion support.
- Improve first-run setup, empty states, error messages, and onboarding guidance.
- Improve desktop/mobile CSS maintainability and responsive behavior.
- Continue reducing unnecessary external asset dependencies where practical for self-hosted and offline operation.

## Backend and operations

- Improve email performance through measured investigation of fetching, caching, attachment handling, searching, and sending.
- Expand regression coverage for provider setup, endpoint probing, and degraded service states.
- Improve task-scheduler defaults, reliability, and operational visibility.
- Improve backup and recovery guidance for persistent application data.
- Continue reviewing administrative capabilities, sensitive integrations, and their authorization boundaries.

## Not a current priority

- Adding more themes without a clear product need.
- Broad rewrites without demonstrated value.
- Framework migrations or architectural changes undertaken solely to reduce file counts.
- Uncoordinated changes to the temporarily frozen agent-runtime contracts.

## Contributing

Before starting work:

1. Read [CONTRIBUTING.md](CONTRIBUTING.md).
2. Search existing issues and PRs to avoid duplicating work.
3. Coordinate structural changes through #4071 and stabilization work through the milestone.
4. Open a focused issue where needed and follow the existing contribution templates.
5. Provide relevant tests, runtime evidence, and screenshots or recordings for visual changes.

For changes involving product direction or difficult-to-reverse contracts, follow the [feature proposal process](docs/maintainers/product-and-features.md).

Security vulnerabilities must be reported privately through [SECURITY.md](SECURITY.md).