matrx-scheduler 0.3.0__tar.gz

matrx_scheduler-0.3.0/.gitignore

@@ -0,0 +1,257 @@
+*.pyc
+secrets/
+ignore/
+temp/
+logs/
+todo
+text_notes/
+aidream/secrets/2.env
+automation_matrix/matrix_processing/temp/*
+cd
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.venv/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+# The blanket lib/ rule above is from the standard Python .gitignore template
+# and was silently swallowing TS source under the SPA `src/lib/` folders.
+# Re-allow them explicitly so frontend builds don't ship without their lib layer.
+!dashboard/src/lib/
+!dashboard/src/lib/**
+!workflow-studio/src/lib/
+!workflow-studio/src/lib/**
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+ai/tests/clean_response.json
+ai/tests/cx_storage_response.json
+ai/tests/execution_test.py
+ai/tests/final_response.json
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env_remote
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.env.armanonly
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# random armani files
+/armani_dev/secrets/
+/armani/
+/_armani/
+
+
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.vscode/
+/node_modules/
+
+dump.rdb
+
+frontend/
+
+# AME Temp Files and directory structure
+# Ignore all files in the temp directory and its subdirectories
+/temp/**/*
+/tmp/**/*
+
+# Allow .gitkeep files to retain directory structure
+!/temp/**/.gitkeep
+!/tmp/**/.gitkeep
+
+# Armani
+.history*
+.history/
+local_data/
+local_reports_data/
+webscraper/quick_scrapes/temp/
+automation_matrix/ai_apis/fireworks/_dev/*
+automation_matrix/ai_apis/fireworks/_dev/fireworks_sample.py
+*.pdf
+*.flac
+*.mp3
+*.wav
+miniconda.sh
+/database/python_sql/temp_data/
+ .history*
+ .history/
+.history/
+
+_dev/
+/_dev/
+requirements_filtered.txt
+
+# matrx-dev-tools backups
+.env-backups/
+# Matrx Ship config (contains API key)
+.matrx-ship.json
+
+# Matrx config (contains API keys)
+.matrx.json
+.matrx-tools.conf
+
+# Claude Code local worktrees and per-user settings
+.claude/worktrees/
+.claude/settings.local.json
+
+# Append-only snapshots from matrx_utils.update_history (unbounded; do not commit)
+common/utils/data_in_code/data_history.json
+packages/matrx-utils/matrx_utils/data_in_code/data_history.json
+
+# Tool-dispatch debug logs — one file per server start, never committed
+.matrx-debug/
+
+# macOS Finder metadata
+.DS_Store
+**/.DS_Store
+
+# Environment files
+.env
+.env.*
+*.env
+*.env.*
+
+# Keep safe templates trackable
+!.env.example
+!.env.sample
+!.env.template

matrx_scheduler-0.3.0/CLAUDE.md

@@ -0,0 +1,103 @@
+# matrx-scheduler — CLAUDE.md
+
+Standalone PyPI-publishable Python package. Server-side executor for the
+`sch_*` scheduling spine shared with matrx-frontend and matrx-extend.
+
+## Package independence
+
+Per `aidream/CLAUDE.md` (top-level): packages MUST NOT import from `aidream/`
+or root-level modules. matrx-scheduler reads `_ext.py` for host-supplied
+dependencies via `configure(...)` — never reaches out.
+
+Dependency graph (inter-package):
+
+```
+matrx-utils                  (foundation — no matrx deps)
+   ▲
+matrx-scheduler              (needs: matrx-utils + host-injected
+                              supabase / context / agent_runner)
+```
+
+## Public API
+
+```python
+import matrx_scheduler
+
+matrx_scheduler.configure(
+    supabase_client=...,       # supabase-py async client
+    surface="server",
+    agent_runner=...,          # async callable(AgentRunInput) -> AgentRunResult
+    get_app_context=...,       # () -> AppContext | None
+    scan_interval_seconds=5.0,
+    lease_seconds=600,
+)
+
+# Background loop
+await matrx_scheduler.start_scanner()
+await matrx_scheduler.stop_scanner()
+
+# Cron helpers (used by the /scheduling/* routes)
+matrx_scheduler.validate_cron("0 9 * * 1-5", "America/Los_Angeles")
+matrx_scheduler.next_n_fires("0 9 * * 1-5", "UTC", n=5)
+matrx_scheduler.compute_next_due_at("interval", {"every_seconds": 3600})
+
+# Health
+status: ScannerStatus = matrx_scheduler.status()
+```
+
+## Module layout
+
+- `__init__.py` — public API exports
+- `_ext.py` — host-injection registry (`configure`, `get_ext`)
+- `models.py` — Pydantic models for sch_task / sch_agent_task / sch_trigger /
+  sch_run + the AgentRunInput/Result contract
+- `queries.py` — Supabase access (the only place that calls `.table('sch_*')`)
+- `scanner.py` — background asyncio loop
+- `runner.py` — drives a single claimed run end-to-end
+- `next_due.py` — `compute_next_due_at(...)` per trigger type
+- `cron_helpers.py` — `croniter`-backed validators
+
+## Invariants
+
+1. **Atomic claim, not "read-then-write".** Scanner finds candidates, then
+   each call to `queries.claim_task` does the concurrency check (active runs
+   count) and inserts the sch_run row in one go. Multiple scanners racing
+   the same task can't double-run because `max_concurrent` is enforced
+   inside the claim.
+2. **DB owns `sch_task.next_due_at`.** After every recurring fire, the
+   scheduler calls `advance_trigger_next_due_at` on `sch_trigger`; the DB
+   trigger `sch_trigger_cascade_next_due_at` updates `sch_task.next_due_at`.
+   Don't UPDATE the parent column directly from the package.
+3. **Lease expiry sweeps run every tick.** Crashed runners leave behind
+   `status IN (claimed,running) AND claim_expires_at < now()` rows. Scanner
+   marks them `failed` so the trigger&apos;s next firing can re-enqueue.
+4. **Heartbeat conversation continuity.** First run of a heartbeat trigger
+   sets `sch_agent_task.persistent_conversation_id` from the runner&apos;s
+   `result.conversation_id`. Subsequent runs use it. Don&apos;t recreate.
+5. **Host-injected agent_runner is fire-and-forget from the scheduler's POV.**
+   It must complete or raise; the scheduler doesn&apos;t poll progress.
+   Inside the runner, use matrx-connect&apos;s streaming infra normally.
+
+## Where this is wired
+
+- aidream `package_integration.py::_configure_matrx_scheduler` — startup config.
+- aidream `api/app.py` — `start_scanner()` in lifespan when
+  `AIDREAM_SCHEDULER=1`. Stops on shutdown.
+- aidream `api/routers/scheduling.py` — 5 HTTP endpoints under `/scheduling`
+  consumed by matrx-frontend.
+
+## Tests
+
+`tests/test_next_due.py` and `tests/test_cron_helpers.py` cover all 5 trigger
+types and the cron parser. Run with:
+
+```bash
+uv run pytest packages/matrx-scheduler/tests
+```
+
+## Related
+
+- Spec: matrx-frontend `docs/SCHEDULING.md`
+- Migrations: matrx-frontend `migrations/sch_*.sql` (the spine is shared)
+- FE control plane: matrx-frontend `features/scheduling/FEATURE.md`
+- Browser-context executor: matrx-extend `src/lib/agenda/*`

matrx_scheduler-0.3.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: matrx-scheduler
+Version: 0.3.0
+Summary: Server-side execution engine for the matrx scheduling spine (sch_* tables): scanner, claim, runner, cron parser, HTTP API.
+Author-email: Matrx <admin@aimatrx.com>
+License: MIT
+Keywords: agents,cron,matrx,scheduler,supabase
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: croniter>=2.0
+Requires-Dist: matrx-utils
+Requires-Dist: pydantic>=2.12
+Requires-Dist: supabase>=2.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115; extra == 'api'
+Requires-Dist: httpx>=0.27; extra == 'api'
+Requires-Dist: matrx-connect; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.115; extra == 'dev'
+Requires-Dist: freezegun>=1.4; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: matrx-connect; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: host
+Requires-Dist: matrx-ai; extra == 'host'
+Requires-Dist: matrx-connect; extra == 'host'
+Requires-Dist: matrx-orm; extra == 'host'
+Description-Content-Type: text/markdown
+
+# matrx-scheduler
+
+Server-side execution engine for the matrx scheduling spine (`sch_*` tables in
+Supabase). Provides:
+
+- a scanner loop that claims due tasks atomically,
+- a runner that drives the host's agent_runner / tool_runner,
+- an authoritative cron parser + next-due computation,
+- and (since 0.3) an HTTP API surface (FastAPI) for task / trigger / run CRUD,
+  manual fires, scanner status, and cron preview.
+
+Any host application (aidream is the reference) wires it up via `configure()`
+and either runs the scanner directly, mounts the HTTP routes, or both.
+
+## What it does (under the hood)
+
+- Polls `sch_task` for rows where `next_due_at <= now()` and the host surface
+  is in `surfaces[]` (or `'any'`).
+- Atomically claims a candidate by inserting a `sch_run` with `claim_token`
+  and `claim_expires_at` (the lease).
+- Drives the matrx-ai agent runner (host-injected) against the claimed task,
+  or the host's tool_runner for `kind='tool'`.
+- Writes back results (`status`, `result_summary`, `output_ref`, etc.).
+- Recomputes the next fire time on recurring triggers; the DB cascade
+  updates `sch_task.next_due_at` automatically.
+
+## Capability-within, injection-without
+
+`matrx-scheduler` doesn't import from a host app. It exposes a `configure()`
+function the host calls at startup, passing in:
+
+- `supabase_client` — service-role client used by the SCANNER to read sch_task
+  across users and update lease state.
+- `surface` — the string this host identifies as in `sch_task.surfaces[]`
+  (e.g. `'server'` for aidream, `'desktop'` for matrx-local).
+- `agent_runner` — callable that runs an agent (kind='agent' tasks).
+- `tool_runner` — optional callable for kind='tool' tasks. Hosts that don't
+  claim tool tasks (e.g. aidream itself) leave this unset.
+- `user_supabase_factory` — optional callable `(user_jwt) -> AsyncClient`
+  used by the HTTP routes to build per-request user-scoped clients. If not
+  provided, the package falls back to an env-based factory keyed on
+  `SUPABASE_MATRIX_URL` + `SUPABASE_MATRIX_PUBLISHABLE_KEY`.
+- `get_app_context`, `emitter_factory`, `scan_interval_seconds`,
+  `lease_seconds` — see the `_ext.configure` docstring.
+
+Install with the `host` extra (`pip install matrx-scheduler[host]`) when
+using it inside a full host app. Add the `api` extra
+(`pip install matrx-scheduler[api]`) to mount the HTTP routes.
+
+## HTTP API
+
+Available since 0.3. Optional — drop the import if you only want the scanner.
+
+```python
+from fastapi import FastAPI
+import matrx_scheduler
+
+app = FastAPI()
+
+# Host startup wiring (any host).
+matrx_scheduler.configure(
+    supabase_client=service_role_client,
+    surface="server",  # or "desktop", "extension", ...
+    agent_runner=my_agent_runner,
+    user_supabase_factory=my_user_client_factory,  # optional
+)
+await matrx_scheduler.start_scanner()
+
+# Mount the HTTP routes.
+matrx_scheduler.api.include_routers(app, prefix="/scheduler")
+```
+
+### Endpoints
+
+All routes use `matrx_connect.AppContext` via `Depends(context_dep)`. Every
+write goes through a per-request Supabase client built from the caller's JWT;
+RLS is the only line of authority on row ownership. The service-role client
+(used by the scanner) is **never** accessible from these routes.
+
+| Method | Path                                    | Purpose                                              |
+| ------ | --------------------------------------- | ---------------------------------------------------- |
+| POST   | `/scheduler/tasks`                      | Create a task (optionally with agent_task + trigger) |
+| GET    | `/scheduler/tasks`                      | List tasks (filter by kind, enabled)                 |
+| GET    | `/scheduler/tasks/{id}`                 | Get task hydrated with agent_task, triggers, runs    |
+| PATCH  | `/scheduler/tasks/{id}`                 | Patch task fields (title, enabled, tags, etc.)       |
+| DELETE | `/scheduler/tasks/{id}`                 | Soft-delete (set enabled=false)                      |
+| POST   | `/scheduler/tasks/{id}/run-now`         | Enqueue a manual run via `sch_enqueue_manual_run`    |
+| GET    | `/scheduler/triggers?task_id=...`       | List triggers for a task                             |
+| POST   | `/scheduler/triggers`                   | Create a trigger on an existing task                 |
+| PATCH  | `/scheduler/triggers/{id}`              | Patch a trigger (recomputes next_due_at if type/config changed) |
+| DELETE | `/scheduler/triggers/{id}`              | Hard-delete a trigger                                |
+| GET    | `/scheduler/runs?task_id=...&status=...`| List run history                                     |
+| GET    | `/scheduler/runs/{id}`                  | Get one run                                          |
+| POST   | `/scheduler/cron/validate`              | Validate a cron expression + preview next N fires    |
+| POST   | `/scheduler/cron/preview-fires`         | Preview next-fire times for any trigger config       |
+| POST   | `/scheduler/compute-next-due-at`        | Compute the single next due_at for a trigger config  |
+| GET    | `/scheduler/status`                     | Scanner health (admin only)                          |
+
+### Co-existence with aidream's `/scheduling/*`
+
+aidream had a small router at `/scheduling/*` (cron validation, run-now,
+admin force-disable) before this surface existed. The package routes use
+`/scheduler/*` (singular) so they don't collide. aidream can mount both
+simultaneously, or migrate clients to the package routes opportunistically.
+matrx-local mounts only the package routes; it has no `/scheduling/*` routes
+to begin with.
+
+See `docs/SCHEDULING.md` in the matrx-frontend repo for the full data-model
+spec, trigger taxonomy, and lifecycle.

matrx_scheduler-0.3.0/README.md

@@ -0,0 +1,109 @@
+# matrx-scheduler
+
+Server-side execution engine for the matrx scheduling spine (`sch_*` tables in
+Supabase). Provides:
+
+- a scanner loop that claims due tasks atomically,
+- a runner that drives the host's agent_runner / tool_runner,
+- an authoritative cron parser + next-due computation,
+- and (since 0.3) an HTTP API surface (FastAPI) for task / trigger / run CRUD,
+  manual fires, scanner status, and cron preview.
+
+Any host application (aidream is the reference) wires it up via `configure()`
+and either runs the scanner directly, mounts the HTTP routes, or both.
+
+## What it does (under the hood)
+
+- Polls `sch_task` for rows where `next_due_at <= now()` and the host surface
+  is in `surfaces[]` (or `'any'`).
+- Atomically claims a candidate by inserting a `sch_run` with `claim_token`
+  and `claim_expires_at` (the lease).
+- Drives the matrx-ai agent runner (host-injected) against the claimed task,
+  or the host's tool_runner for `kind='tool'`.
+- Writes back results (`status`, `result_summary`, `output_ref`, etc.).
+- Recomputes the next fire time on recurring triggers; the DB cascade
+  updates `sch_task.next_due_at` automatically.
+
+## Capability-within, injection-without
+
+`matrx-scheduler` doesn't import from a host app. It exposes a `configure()`
+function the host calls at startup, passing in:
+
+- `supabase_client` — service-role client used by the SCANNER to read sch_task
+  across users and update lease state.
+- `surface` — the string this host identifies as in `sch_task.surfaces[]`
+  (e.g. `'server'` for aidream, `'desktop'` for matrx-local).
+- `agent_runner` — callable that runs an agent (kind='agent' tasks).
+- `tool_runner` — optional callable for kind='tool' tasks. Hosts that don't
+  claim tool tasks (e.g. aidream itself) leave this unset.
+- `user_supabase_factory` — optional callable `(user_jwt) -> AsyncClient`
+  used by the HTTP routes to build per-request user-scoped clients. If not
+  provided, the package falls back to an env-based factory keyed on
+  `SUPABASE_MATRIX_URL` + `SUPABASE_MATRIX_PUBLISHABLE_KEY`.
+- `get_app_context`, `emitter_factory`, `scan_interval_seconds`,
+  `lease_seconds` — see the `_ext.configure` docstring.
+
+Install with the `host` extra (`pip install matrx-scheduler[host]`) when
+using it inside a full host app. Add the `api` extra
+(`pip install matrx-scheduler[api]`) to mount the HTTP routes.
+
+## HTTP API
+
+Available since 0.3. Optional — drop the import if you only want the scanner.
+
+```python
+from fastapi import FastAPI
+import matrx_scheduler
+
+app = FastAPI()
+
+# Host startup wiring (any host).
+matrx_scheduler.configure(
+    supabase_client=service_role_client,
+    surface="server",  # or "desktop", "extension", ...
+    agent_runner=my_agent_runner,
+    user_supabase_factory=my_user_client_factory,  # optional
+)
+await matrx_scheduler.start_scanner()
+
+# Mount the HTTP routes.
+matrx_scheduler.api.include_routers(app, prefix="/scheduler")
+```
+
+### Endpoints
+
+All routes use `matrx_connect.AppContext` via `Depends(context_dep)`. Every
+write goes through a per-request Supabase client built from the caller's JWT;
+RLS is the only line of authority on row ownership. The service-role client
+(used by the scanner) is **never** accessible from these routes.
+
+| Method | Path                                    | Purpose                                              |
+| ------ | --------------------------------------- | ---------------------------------------------------- |
+| POST   | `/scheduler/tasks`                      | Create a task (optionally with agent_task + trigger) |
+| GET    | `/scheduler/tasks`                      | List tasks (filter by kind, enabled)                 |
+| GET    | `/scheduler/tasks/{id}`                 | Get task hydrated with agent_task, triggers, runs    |
+| PATCH  | `/scheduler/tasks/{id}`                 | Patch task fields (title, enabled, tags, etc.)       |
+| DELETE | `/scheduler/tasks/{id}`                 | Soft-delete (set enabled=false)                      |
+| POST   | `/scheduler/tasks/{id}/run-now`         | Enqueue a manual run via `sch_enqueue_manual_run`    |
+| GET    | `/scheduler/triggers?task_id=...`       | List triggers for a task                             |
+| POST   | `/scheduler/triggers`                   | Create a trigger on an existing task                 |
+| PATCH  | `/scheduler/triggers/{id}`              | Patch a trigger (recomputes next_due_at if type/config changed) |
+| DELETE | `/scheduler/triggers/{id}`              | Hard-delete a trigger                                |
+| GET    | `/scheduler/runs?task_id=...&status=...`| List run history                                     |
+| GET    | `/scheduler/runs/{id}`                  | Get one run                                          |
+| POST   | `/scheduler/cron/validate`              | Validate a cron expression + preview next N fires    |
+| POST   | `/scheduler/cron/preview-fires`         | Preview next-fire times for any trigger config       |
+| POST   | `/scheduler/compute-next-due-at`        | Compute the single next due_at for a trigger config  |
+| GET    | `/scheduler/status`                     | Scanner health (admin only)                          |
+
+### Co-existence with aidream's `/scheduling/*`
+
+aidream had a small router at `/scheduling/*` (cron validation, run-now,
+admin force-disable) before this surface existed. The package routes use
+`/scheduler/*` (singular) so they don't collide. aidream can mount both
+simultaneously, or migrate clients to the package routes opportunistically.
+matrx-local mounts only the package routes; it has no `/scheduling/*` routes
+to begin with.
+
+See `docs/SCHEDULING.md` in the matrx-frontend repo for the full data-model
+spec, trigger taxonomy, and lifecycle.

matrx_scheduler-0.3.0/matrx_scheduler/__init__.py

@@ -0,0 +1,85 @@
+"""
+matrx-scheduler — server-side execution engine for the sch_* scheduling spine.
+
+Public API:
+    configure(...)          — wire host-supplied dependencies (call at startup)
+    start_scanner()         — spawn the background scanner asyncio task
+    stop_scanner()          — graceful shutdown
+    status()                — current scanner health (last tick, queue depth, etc.)
+    validate_cron(...)      — server-authoritative cron expression validator
+    next_n_fires(...)       — preview a cron expression's next N fires
+    compute_next_due_at(...) — compute the next fire time for any trigger config
+
+HTTP API (optional, requires matrx-connect + fastapi):
+    matrx_scheduler.api.include_routers(app, prefix="/scheduler")
+
+Models (Pydantic):
+    SchTask, SchAgentTask, SchTrigger, SchRun
+    HydratedTask, AgentRunInput, AgentRunResult
+"""
+
+from __future__ import annotations
+
+from ._ext import configure, has_ext, is_configured
+from .cron_helpers import (
+    fire_count_in_window,
+    next_n_fires,
+    validate_cron,
+)
+from .models import (
+    AgentRunInput,
+    AgentRunResult,
+    AuthMode,
+    HydratedTask,
+    RunStatus,
+    SchAgentTask,
+    SchRun,
+    SchTask,
+    SchTrigger,
+    ToolRunInput,
+    TriggerType,
+)
+
+
+__version__ = "0.3.0"
+from .next_due import compute_next_due_at
+from .scanner import (
+    ScannerStatus,
+    is_running,
+    start_scanner,
+    status,
+    stop_scanner,
+)
+
+
+__all__ = [
+    # configuration
+    "configure",
+    "is_configured",
+    "has_ext",
+    # scanner
+    "start_scanner",
+    "stop_scanner",
+    "status",
+    "is_running",
+    "ScannerStatus",
+    # cron helpers
+    "validate_cron",
+    "next_n_fires",
+    "fire_count_in_window",
+    "compute_next_due_at",
+    # models
+    "SchTask",
+    "SchAgentTask",
+    "SchTrigger",
+    "SchRun",
+    "HydratedTask",
+    "AgentRunInput",
+    "AgentRunResult",
+    "ToolRunInput",
+    "TriggerType",
+    "RunStatus",
+    "AuthMode",
+    # version
+    "__version__",
+]