[RohithPariki]

Problem

Currently, adding custom transcript harvesters or replay/optimizer backends to SkillOpt-Sleep requires modifying core codebase files or writing external harness wrappers. As noted in #314, external ecosystems (such as Antigravity, zcode, Crush, or specialized LLM harnesses) had no sanctioned plugin mechanism to register their harvesters or backends directly into skillopt-sleep. Furthermore, external harvesters could not reuse the internal session sanitization, feedback detection, and meta-prompt filtering logic without reaching into private underscored functions.

Items 3 and 4 of #314 were previously merged (in #350 and #322). On Nov 4, maintainer Yifan Yang (@Yif-Yang) confirmed:

"Still open: entry-point/module registration for sources and backends (items 1–2) and the public helper API (item 5), so this issue stays open."

Solution

This PR implements items 1, 2, and 5 of #314:

1. Pluggable Transcript Sources (skillopt_sleep/harvest_sources.py):
   • Consults the skillopt_sleep.sources entry-point group and in-memory register_source(name, fn) registry alongside built-in harvesters.
   • Adds --source-module pkg.mod:func (and source_module config support) for loading unpackaged adapter functions directly.
   • normalize_transcript_source() validates against all built-in, entry-point, and registered source names with an informative error listing available options.
2. Pluggable Backends (skillopt_sleep/backend.py):
   • Consults the skillopt_sleep.backends entry-point group and in-memory register_backend(name, factory) registry.
   • Adds --backend-module pkg.mod:Class (and backend_module config support) for loading unpackaged backend classes or factories directly.
   • get_backend() validates unknown names against all available backends, raising an informative ValueError.
   • build_backend() wires backend_module through to single or dual backend construction.
3. CLI Arguments (skillopt_sleep/__main__.py):
   • Added --source-module and --backend-module flags.
   • Relaxed hardcoded choices on --source and --backend so registered and entry-point names are cleanly accepted from the CLI.
4. Public Harvest Helper API (skillopt_sleep/harvest.py):
   • Promoted and exported is_headless_replay, is_agent_session, is_meta_prompt, detect_feedback, and redact_secrets in __all__, allowing external adapters to apply identical filtering and secret redaction.
5. Changelog:
   • Added entry under ## [Unreleased] / ### Added.

Testing

• Added comprehensive unit tests in tests/test_sleep_pluggable_registry.py:
  • test_custom_source_registration_and_harvest: Validates register_source() and invocation in harvest_for_config().
  • test_entry_point_source_discovery: Mocks skillopt_sleep.sources entry points.
  • test_source_module_invocation: Validates loading via module:func spec.
  • test_unknown_source_raises_informative_error: Verifies ValueError lists available sources.
  • test_custom_backend_registration: Validates register_backend() and get_backend().
  • test_entry_point_backend_discovery: Mocks skillopt_sleep.backends entry points.
  • test_backend_module_invocation: Validates loading via module:Class spec.
  • test_unknown_backend_raises_informative_error: Verifies ValueError lists available backends.
  • test_public_harvest_helpers: Verifies is_meta_prompt, detect_feedback, is_agent_session, is_headless_replay, and redact_secrets.
• All 9/9 tests in tests/test_sleep_pluggable_registry.py pass cleanly.
• Linter ruff check passes with 0 errors.

Risk

Low. Fully backwards-compatible. All existing built-in sources (claude, codex, copilot, cursor, pi, opencode, auto) and backends (azure, claude, codex, copilot, cursor, handoff, mock, opencode, pi) remain default and behaviorally identical.

Fixes #314