catence 0.2.0-beta.2 → 0.2.0-beta.21

package/docs/llm-providers.md

@@ -2,9 +2,11 @@
 
 Catence Console talks to a model through [LiteLLM](https://docs.litellm.ai/).
 There are exactly three provider shapes: **OpenAI**, **Anthropic**, and a
-generic **OpenAI-compatible** profile. Azure and Opencode are not special cases
-in the code: both are reached through the OpenAI-compatible profile, and the
-steps for each are documented below.
+generic **OpenAI-compatible** profile. Azure is not a special case in the code:
+it is reached through the OpenAI-compatible profile. OpenCode Go can be reached
+the same way through a local gateway, or directly at its own OpenAI-compatible
+endpoint with native `openai/…` and `anthropic/…` model names; the steps for
+each are documented below.
 
 ## How configuration is split
 
@@ -166,9 +168,90 @@ Notes:
 
 ### Opencode
 
-Opencode itself does not expose an OpenAI-compatible server; its `serve` command
-publishes Opencode's own API. To reuse the providers you already configured in
-Opencode, run an OpenAI-compatible gateway such as the
+[OpenCode Go](https://opencode.ai) publishes an OpenAI-compatible API at
+`https://opencode.ai/zen/go/v1`; its `GET /v1/models` listing is public and does
+not require a key. The Console can use it directly, so most setups do not need a
+local gateway.
+
+The repository includes a discovery script that fetches the live model list and
+merges ready-made Console profiles into `config.json`. From a Catence checkout:
+
+```sh
+npm run discover:opencode-go -- --write ~/.catence/config.json
+```
+
+The script adds two profiles, because OpenCode Go routes model families through
+different API shapes:
+
+- `opencode-go` — chat and responses models, base
+  `https://opencode.ai/zen/go/v1` (LiteLLM `openai/…` names).
+- `opencode-go-messages` — messages models, base `https://opencode.ai/zen/go`
+  (LiteLLM `anthropic/…` names).
+
+| Family | Profile prefix | Example |
+| --- | --- | --- |
+| Chat | `openai/<id>` | `openai/deepseek-v4-flash` |
+| Responses | `openai/responses/<id>` | `openai/responses/grok-4.5` |
+| Messages | `anthropic/<id>` | `anthropic/minimax-m2.5` |
+
+The script warns on stderr and skips any model that does not fit one of these
+families. Rerun it to refresh the model lists; existing profiles, limits, and
+`defaultProfile` are preserved unless `--set-default` is passed. Re-running
+never discards your own tweaks: per-model custom labels, `reasoningEffort`
+pins, and `variants` maps survive every refresh. Models that have dropped out
+of the live catalog are pruned from the managed profiles, so the Console never
+offers a route the gateway no longer serves; if a pruned model was the
+profile's default, discovery selects a current one instead.
+
+You do not have to run the script manually: the Console dashboard's **Sync
+data** button (and `POST /api/v1/sync` with `"refreshModels": true`) refreshes
+these profiles from the live catalog before starting a data sync, and the
+Models page's **Discover OpenCode Go models** button (or
+`POST /api/v1/models/discover`) refreshes them without syncing anything.
+Discovery failures — offline machine, catalog unreachable — are reported as a
+warning and never block or fail the sync itself.
+
+```sh
+export OPENCODE_GO_API_KEY='…'                      # any non-empty value satisfies the key check
+export OPENCODE_GO_API_BASE='https://opencode.ai/zen/go/v1'
+export OPENCODE_GO_MESSAGES_API_BASE='https://opencode.ai/zen/go'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "opencode-go",
+    "profiles": {
+      "opencode-go": {
+        "label": "OpenCode Go",
+        "defaultModel": "flash",
+        "models": {
+          "flash": { "label": "DeepSeek V4 flash", "model": "openai/deepseek-v4-flash" },
+          "grok": { "label": "Grok 4.5", "model": "openai/responses/grok-4.5" }
+        },
+        "apiKeyEnv": "OPENCODE_GO_API_KEY",
+        "apiBaseEnv": "OPENCODE_GO_API_BASE"
+      },
+      "opencode-go-messages": {
+        "label": "OpenCode Go messages",
+        "defaultModel": "minimax",
+        "models": {
+          "minimax": { "label": "MiniMax M2.5", "model": "anthropic/minimax-m2.5" }
+        },
+        "apiKeyEnv": "OPENCODE_GO_API_KEY",
+        "apiBaseEnv": "OPENCODE_GO_MESSAGES_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Verify with `catence-console doctor`. The `responses` models
+(`openai/responses/…`) go through LiteLLM's responses bridge and are the least
+battle-tested path; smoke-test one chat turn before relying on them.
+
+If you instead want to reuse the providers already configured in your local
+Opencode CLI, run an OpenAI-compatible gateway such as the
 [`opencode-llm-proxy`](https://github.com/KochC/opencode-llm-proxy) plugin, which
 serves Chat Completions at `http://127.0.0.1:4010/v1` and lists every configured
 model as `provider/model`.
@@ -202,6 +285,83 @@ Notes:
   `OPENCODE_LLM_PROXY_TOKEN`; otherwise any non-empty value satisfies the
   profile's required-environment check.
 
+### Opencode Zen
+
+[OpenCode Zen](https://opencode.ai/zen) is a hosted model API with a curated
+selection of coding and reasoning models. It exposes an OpenAI-compatible
+endpoint at `https://opencode.ai/zen/v1` with a public `GET /v1/models`
+listing. Several models are available for free (no billing details required);
+paid models require an API key from [opencode.ai/auth](https://opencode.ai/auth).
+
+The repository includes a discovery script that fetches the live model list and
+merges ready-made Console profiles into `config.json`. From a Catence checkout:
+
+```sh
+npm run discover:opencode-zen -- --write ~/.catence/config.json
+```
+
+Add `--free-only` to include only the free models.
+
+The script adds two profiles, because OpenCode Zen routes model families through
+different API shapes:
+
+- `opencode-zen` — chat/completions models (most models, including all free
+  models), base `https://opencode.ai/zen/v1` (LiteLLM `openai/<id>` names).
+- `opencode-zen-responses` — responses API models (GPT-5.x series), base
+  `https://opencode.ai/zen/v1` (LiteLLM `openai/responses/<id>` names).
+
+| Family | Profile prefix | Example |
+| --- | --- | --- |
+| Chat | `openai/<id>` | `openai/deepseek-v4-flash-free` |
+| Responses | `openai/responses/<id>` | `openai/responses/gpt-5.6-luna` |
+
+Free models carry a `-free` suffix (e.g., `deepseek-v4-flash-free`,
+`nemotron-3-ultra-free`, `big-pickle`). The discovery script recognises them
+automatically; `--free-only` filters the list to free models only.
+
+```sh
+export OPENCODE_API_KEY='…'                         # required for paid models; any non-empty value for free
+export OPENCODE_ZEN_API_BASE='https://opencode.ai/zen/v1'
+export OPENCODE_ZEN_RESPONSES_API_BASE='https://opencode.ai/zen/v1'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "opencode-zen",
+    "profiles": {
+      "opencode-zen": {
+        "label": "OpenCode Zen",
+        "defaultModel": "deepseek-v4-flash-free",
+        "models": {
+          "deepseek-v4-flash-free": { "label": "DeepSeek V4 Flash Free", "model": "openai/deepseek-v4-flash-free" },
+          "nemotron-3-ultra-free": { "label": "Nemotron 3 Ultra Free", "model": "openai/nemotron-3-ultra-free" },
+          "big-pickle": { "label": "Big Pickle", "model": "openai/big-pickle" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      },
+      "opencode-zen-responses": {
+        "label": "OpenCode Zen (Responses)",
+        "defaultModel": "gpt-5.6-luna",
+        "models": {
+          "gpt-5.6-luna": { "label": "GPT 5.6 Luna", "model": "openai/responses/gpt-5.6-luna" },
+          "gpt-5.6-terra": { "label": "GPT 5.6 Terra", "model": "openai/responses/gpt-5.6-terra" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_RESPONSES_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Verify with `catence-console doctor`. The `responses` models
+(`openai/responses/…`) go through LiteLLM's responses bridge and are the least
+battle-tested path; smoke-test one chat turn before relying on them.
+
+The same `OPENCODE_API_KEY` works for both Opencode Go and Opencode Zen.
+
 ## Multiple deployments per provider
 
 A profile can list several models under one set of credentials; the Console
@@ -226,6 +386,58 @@ settings then offer a per-deployment choice.
 }
 ```
 
+## Reasoning effort
+
+Models expose a per-chat **Thinking effort** dropdown in the Console settings.
+By default it offers the OpenAI-standard levels — `minimal`, `low`, `medium`,
+`high`, `xhigh` — which suit OpenAI and most OpenAI-compatible endpoints.
+
+Some models (for example DeepSeek V4 Flash) use their own reasoning-effort
+scheme rather than the OpenAI-standard list. For those, declare `variants` on
+the model: a mapping of dropdown label to the exact value sent to the provider.
+The chat dropdown then shows `Provider default` plus each label instead of the
+OpenAI-standard list.
+
+```jsonc
+{
+  "console": {
+    "profiles": {
+      "opencode-zen": {
+        "label": "OpenCode Zen",
+        "defaultModel": "deepseek-v4-flash-free",
+        "models": {
+          "deepseek-v4-flash-free": {
+            "label": "DeepSeek V4 Flash Free",
+            "model": "openai/deepseek-v4-flash-free",
+            "variants": { "High": "high", "Max": "max" }
+          }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Selecting a variant sends that value verbatim as `reasoning_effort` (with
+`allowed_openai_params` so LiteLLM forwards it for OpenAI-compatible models).
+The `Provider default` option sends no reasoning effort at all.
+
+An explicitly empty `variants` map disables reasoning effort for that model:
+no `reasoning_effort` is sent (the agent guards against it) and the chat
+**Thinking effort** dropdown is disabled in the UI. This suits models that
+reject the parameter, such as MiMo, which expects its own `thinking` toggle
+instead. `variants: {}` cannot be combined with a fixed `reasoningEffort` on
+the same model.
+
+You can also pin a fixed level with `reasoningEffort` on the model, or a
+profile-wide default with `defaultReasoningEffort` (OpenAI-standard values
+only). Precedence: per-chat dropdown selection > model `reasoningEffort` >
+profile `defaultReasoningEffort` > provider default. The **Thinking effort**
+dropdown is rebuilt whenever the **Model** dropdown changes, so its options
+(and disabled state) always reflect the selected model.
+
 ## Verifying a profile
 
 `catence-console doctor` reports, for each profile, which environment variables
@@ -235,3 +447,34 @@ prints credential values.
 ```sh
 catence-console doctor --home "$HOME/.catence" --mcp-url http://127.0.0.1:8787/mcp
 ```
+
+On Docker, the deploy scaffold includes a helper that runs it inside the
+running container (`exec`, not `run` — the container's loopback hosts the live
+MCP server and the `.env` provider keys are in its environment):
+
+```sh
+./catence-deploy/doctor.sh
+```
+
+## Docker: generating the Console login hash
+
+`deploy-console.sh` writes a small helper into the deployment directory. Run it
+once after the script to generate the bcrypt hash for
+`CATENCE_CONSOLE_PASSWORD_HASH` — it prompts for the password on the terminal,
+never echoes it, and uses the compose project so it works no matter what image
+tag the script built:
+
+```sh
+./catence-deploy/hash-password.sh
+```
+
+Paste the output into `CATENCE_CONSOLE_PASSWORD_HASH` in `catence-deploy/.env`,
+then start the stack (`./deploy-console.sh beta` again, or
+`docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env up -d`).
+
+If you prefer, re-run the deploy script with `--generate-secrets` instead and
+answer the interactive password prompt; it saves the hash to `.env` for you.
+Without the helper (for example an older deployment), the equivalent command
+is `docker run --rm -it --entrypoint /opt/catence-console/bin/catence-console
+<image-tag> auth hash-password`, where `<image-tag>` is the tag printed by the
+script.

package/docs/mcp-activity-retrieval.md

@@ -142,35 +142,12 @@ differs from the activity summary, report both values and the difference.
 
 ## Proposed dedicated MCP endpoints
 
-These endpoints are drafts, not registered tools yet. Add them incrementally
-only after their shared service methods and fixture tests exist.
-
-## Implemented fitness and hydration endpoints
-
-- `describe_dataset(dataset)` returns one cataloged schema and its coverage. `training_metric_observations` also reports its observed sports, metric names, units, and source types.
-- `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, and `power_coverage_report` read normalized, source-aware fitness facts. Power tools require an explicit sport or sport family, use `power_bests`/`power_best_facts` for FIT-derived duration values, and do not treat sparse `avg_power` summaries as coverage. `get_vo2max_history` does not default to cycling: omission returns available source labels and requires an explicit choice. For Garmin running VO₂max, request `sport: "running"`; the tool reads the raw `generic` source series and preserves that label on returned observations.
-- `find_activities` is implemented for compact, canonical, paginated activity/race discovery by sport, distance, name, and date. Its race flags are transparent heuristics, not provider-confirmed race metadata.
-- `get_activity_segments` is the required segment/climb path. It performs the
-  targeted Strava hydration before returning the persisted effort and segment
-  facts; an empty result must be interpreted alongside its hydration status.
-- `latest_cycling_activities` returns Garmin source records to avoid silently double-counting linked Intervals summaries; optional multisport parents are explicitly flagged.
-- `cycling_progress_report` composes the preceding read-only outputs with monthly canonical volume/load. It is descriptive, not a physiological model.
-- `hydrate_recent_strava_activities` accepts an explicit list or a bounded date/sport window and awaits each write in sequence. Its unmatched output includes the exact Strava search window and safe-match rejection diagnostics.
-
-### Power investigation procedure
-
-For a question about running or cycling power, do not begin with
-`canonical_activities.avg_power`: it is an activity-summary field and can be
-null even when the FIT stream has power. Instead:
-
-1. Call `describe_dataset` for `power_bests` and use `power_coverage_report`
-   with an explicit `sport` or `sportFamily` to establish coverage and every
-   available duration.
-2. Use `power_curve_trend` with the same selector and
-   `sourceQuality: "garmin_fit_derived"` for comparable monthly curve bests.
-3. Inspect `activity_samples` only for a selected `activity_source_id` when a
-   specific extreme needs validation. Raw sample reads are paginated and are
-   not evidence that the global power dataset is absent.
+These endpoints are **drafts, not registered tools yet**. The current server
+(`src/interfaces/mcp/server.ts`) does not expose them, so an agent cannot call
+them today; they are specified here so semantics and acceptance criteria are
+agreed before implementation. Add them incrementally only after their shared
+service methods and fixture tests exist, then move them to the implemented
+list below.
 
 ### `list_recent_activities`
 
@@ -330,9 +307,39 @@ manifest-only Parquet access, and null handling. It returns no data—not an
 error—when the source has no registered stream, with a caveat explaining that
 sample availability is provider/activity-specific.
 
+## Implemented fitness and hydration endpoints
+
+- `describe_dataset(dataset)` returns one cataloged schema and its coverage. `training_metric_observations` also reports its observed sports, metric names, units, and source types.
+- `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, and `power_coverage_report` read normalized, source-aware fitness facts. Power tools require an explicit sport or sport family, use `power_bests`/`power_best_facts` for FIT-derived duration values, and do not treat sparse `avg_power` summaries as coverage. `get_vo2max_history` does not default to cycling: omission returns available source labels and requires an explicit choice. For Garmin running VO₂max, request `sport: "running"`; the tool reads the raw `generic` source series and preserves that label on returned observations.
+- `find_activities` is implemented for compact, canonical, paginated activity/race discovery by sport, distance, name, and date. Its race flags are transparent heuristics, not provider-confirmed race metadata.
+- `get_activity_segments` is the required segment/climb path. It performs the
+  targeted Strava hydration before returning the persisted effort and segment
+  facts; an empty result must be interpreted alongside its hydration status.
+- `latest_cycling_activities` returns Garmin source records to avoid silently double-counting linked Intervals summaries; optional multisport parents are explicitly flagged.
+- `cycling_progress_report` composes the preceding read-only outputs with monthly canonical volume/load. It is descriptive, not a physiological model.
+- `hydrate_recent_strava_activities` accepts an explicit list or a bounded date/sport window and awaits each write in sequence. Its unmatched output includes the exact Strava search window and safe-match rejection diagnostics.
+
+### Power investigation procedure
+
+For a question about running or cycling power, do not begin with
+`canonical_activities.avg_power`: it is an activity-summary field and can be
+null even when the FIT stream has power. Instead:
+
+1. Call `describe_dataset` for `power_bests` and use `power_coverage_report`
+   with an explicit `sport` or `sportFamily` to establish coverage and every
+   available duration.
+2. Use `power_curve_trend` with the same selector and
+   `sourceQuality: "garmin_fit_derived"` for comparable monthly curve bests.
+3. Inspect `activity_samples` only for a selected `activity_source_id` when a
+   specific extreme needs validation. Raw sample reads are paginated and are
+   not evidence that the global power dataset is absent.
+
 ## Intended agent behaviour
 
-For “how did this go in the context of my recent swims?” an agent should:
+This workflow is the target behaviour once the proposed endpoints above are
+implemented and registered; today the agent must approximate it with
+`find_activities`, `get_activity_segments`, and `read_series`. For “how did
+this go in the context of my recent swims?” an agent should:
 
 1. Use `list_recent_activities` filtered to swimming to identify the selected
    source and comparable source records.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.21",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -28,6 +28,8 @@
     "README.md",
     "config.example.json",
     "docs",
+    "scripts/discover-opencode-go.mjs",
+    "scripts/discover-opencode-zen.mjs",
     "pyproject.toml",
     "uv.lock",
     "python/__init__.py",
@@ -55,6 +57,8 @@
     "mcp": "tsx src/interfaces/mcp/main.ts",
     "console": "uv run --project console catence-console serve",
     "console:doctor": "uv run --project console catence-console doctor",
+    "discover:opencode-go": "node scripts/discover-opencode-go.mjs",
+    "discover:opencode-zen": "node scripts/discover-opencode-zen.mjs",
     "package:check": "npm pack --dry-run",
     "release:check": "node scripts/release-artifacts.mjs check",
     "mcpb:validate": "npm exec --yes --package @anthropic-ai/mcpb -- mcpb validate mcpb/manifest.json",

package/pyproject.toml

@@ -15,7 +15,7 @@ dependencies = [
 
 [tool.uv.sources]
 # fork commit
-garminconnect = { git = "https://github.com/rifusaki/python-garminconnect.git", rev = "732bf14602bce2ca22cb569ba6583c3229bf904d" }
+garminconnect = { git = "https://github.com/rifusaki/python-garminconnect.git", rev = "cd4e3d9ef81a93681950138e08f57af226fd5735" }
 
 [tool.uv]
 package = false

package/python/catence/providers/garmin/cli.py

@@ -4,11 +4,14 @@ import argparse
 import getpass
 import json
 import os
+import signal
+import sys
 from datetime import date
 from pathlib import Path
 
+from .progress import ProgressReporter
 from .staging import StagingWriter
-from .worker import GarminStagingWorker
+from .worker import GarminStagingWorker, WorkerInterrupted
 
 
 def parse_args() -> argparse.Namespace:
@@ -26,6 +29,17 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--historical-only", action="store_true", help="Skip current account and collection endpoints.")
     parser.add_argument("--skip-daily", action="store_true", help="Do not fetch date-scoped daily data.")
     parser.add_argument("--skip-activities", action="store_true", help="Do not fetch date-scoped activities.")
+    parser.add_argument(
+        "--lt-history-from",
+        dest="lt_history_from",
+        type=date.fromisoformat,        help="Backfill lactate-threshold history from this date instead of the daily window.",
+    )
+    parser.add_argument(
+        "--events-from",
+        dest="events_from",
+        type=date.fromisoformat,
+        help="Fetch calendar events from this date instead of the default short lookback.",
+    )
     return parser.parse_args()
 
 
@@ -43,19 +57,39 @@ def main() -> None:
     token_store.parent.mkdir(parents=True, exist_ok=True)
     client = Garmin(email, password, prompt_mfa=lambda: input("Garmin MFA code: "))
     client.login(str(token_store))
+    reporter = ProgressReporter(args.run_id)
+    reporter.set_stage("login")
+    reporter.finish("login")
     known_hashes: dict[str, str] = {}
     if args.known_activities and args.known_activities.exists():
         loaded = json.loads(args.known_activities.read_text(encoding="utf-8"))
         if isinstance(loaded, dict):
             known_hashes = {str(key): str(value) for key, value in loaded.items()}
-    GarminStagingWorker(client, writer, args.data_dir, known_hashes).sync(
-        daily_from_date=None if args.skip_daily else args.daily_from_date or args.from_date,
-        activity_from_date=None if args.skip_activities else args.activity_from_date or args.from_date,
-        to_date=args.to_date,
-        daily_to_date=args.daily_to_date,
-        activity_to_date=args.activity_to_date,
-        include_non_historical=not args.historical_only,
-    )
+    worker = GarminStagingWorker(client, writer, args.data_dir, known_hashes, progress=reporter)
+    interrupt_signal: int | None = None
+
+    def _request_interrupt(signum: int, _frame: object) -> None:
+        nonlocal interrupt_signal
+        interrupt_signal = signum
+        worker.request_interrupt()
+
+    signal.signal(signal.SIGINT, _request_interrupt)
+    signal.signal(signal.SIGTERM, _request_interrupt)
+    try:
+        worker.sync(
+            daily_from_date=None if args.skip_daily else args.daily_from_date or args.from_date,
+            activity_from_date=None if args.skip_activities else args.activity_from_date or args.from_date,
+            to_date=args.to_date,
+            daily_to_date=args.daily_to_date,
+            activity_to_date=args.activity_to_date,
+            include_non_historical=not args.historical_only,
+            lactate_threshold_history_from=args.lt_history_from,
+            events_from=args.events_from.isoformat() if args.events_from else None,
+        )
+    except WorkerInterrupted:
+        reporter.finish("interrupted")
+        raise SystemExit(130 if interrupt_signal == signal.SIGINT else 143)
+    reporter.finish("completed")
 
 
 if __name__ == "__main__":

package/python/catence/providers/garmin/progress.py

@@ -0,0 +1,85 @@
+"""Progress reporting for Garmin sync runs.
+
+Emits single-line JSON progress records (kind: 'progress') on stdout so the
+Node management layer can persist heartbeats without parsing the staging
+JSONL consumed by the importer.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+
+class ProgressReporter:
+    """Throttled progress publisher writing NDJSON records to stdout."""
+
+    def __init__(
+        self,
+        run_id: str,
+        provider: str = "garmin",
+        emit: Callable[[str], None] = lambda line: print(line, flush=True),
+        interval_seconds: float = 2.0,
+    ) -> None:
+        self.run_id = run_id
+        self.provider = provider
+        self.emit = emit
+        self.interval_seconds = interval_seconds
+        self._started = time.monotonic()
+        self._last_emitted = 0.0
+        self.stage = "starting"
+        self.current_step: str | None = None
+        self.completed_units = 0
+        self.total_units: int | None = None
+
+    def set_stage(self, stage: str) -> None:
+        """Switch phases, resetting phase-local counters and forcing a publish."""
+        if stage != self.stage:
+            self.stage = stage
+            self.current_step = None
+            self.completed_units = 0
+            self.total_units = None
+            self.publish(force=True)
+
+    def advance(self, completed: int | None = None, total: int | None = None, step: str | None = None) -> None:
+        if completed is not None:
+            self.completed_units = completed
+        if total is not None:
+            self.total_units = total
+        if step is not None:
+            self.current_step = step
+        self.publish()
+
+    def publish(self, force: bool = False) -> None:
+        now = time.monotonic()
+        if not force and now - self._last_emitted < self.interval_seconds:
+            return
+        self._last_emitted = now
+        elapsed = now - self._started
+        percent = 0.0
+        eta: float | None = None
+        if self.total_units and self.total_units > 0:
+            percent = min(100.0, max(0.0, self.completed_units / self.total_units * 100.0))
+            if self.completed_units > 0 and self.completed_units < self.total_units:
+                rate = elapsed / self.completed_units
+                eta = rate * (self.total_units - self.completed_units)
+        record = {
+            "kind": "progress",
+            "runId": self.run_id,
+            "provider": self.provider,
+            "stage": self.stage,
+            "currentStep": self.current_step,
+            "completedUnits": self.completed_units,
+            "totalUnits": self.total_units,
+            "percentComplete": round(percent, 2),
+            "elapsedSeconds": round(elapsed, 1),
+            "estimatedRemainingSeconds": round(eta, 1) if eta is not None else None,
+            "heartbeatAt": datetime.now(timezone.utc).isoformat(),
+        }
+        self.emit(json.dumps(record, separators=(",", ":")))
+
+    def finish(self, stage: str = "completed") -> None:
+        self.stage = stage
+        self.publish(force=True)

package/python/catence/providers/garmin/registry.py

@@ -32,6 +32,7 @@ GARMIN_READ_METHODS = {
         "get_activity_gear", "download_activity",
     ),
     "workouts": ("get_workouts", "get_scheduled_workouts"),
+    "events": ("get_events",),
     "goals": ("get_goals",),
     "gear": ("get_gear",),
     "golf": ("get_golf_summary",),

package/python/catence/providers/garmin/streams.py

@@ -183,6 +183,44 @@ def fit_archive_to_samples(activity_source_id: str, archive: Path) -> list[dict[
         return []
 
 
+def fit_archive_to_swim_lengths(activity_source_id: str, archive: Path) -> list[dict[str, Any]]:
+    """Best-effort per-length parsing from the FIT 'length' messages; malformed/unavailable archives yield no rows."""
+    try:
+        import fitdecode
+        with zipfile.ZipFile(archive) as zip_file:
+            fit_name = next((name for name in zip_file.namelist() if name.lower().endswith(".fit")), None)
+            if not fit_name:
+                return []
+            with zip_file.open(fit_name) as stream, fitdecode.FitReader(stream) as reader:
+                rows: list[dict[str, Any]] = []
+                for frame in reader:
+                    if not isinstance(frame, fitdecode.records.FitDataMessage) or frame.name != "length":
+                        continue
+                    fields = {field.name: field.value for field in frame.fields}
+                    length_type = str(fields.get("length_type") or "").lower()
+                    start_time = fields.get("start_time") or fields.get("timestamp")
+                    row = {
+                        "lengthIndex": _number(fields.get("message_index")),
+                        "lapIndex": None,
+                        "startTime": start_time.isoformat().replace("+00:00", "Z") if hasattr(start_time, "isoformat") else None,
+                        "durationS": _number(fields.get("total_elapsed_time") or fields.get("total_timer_time")),
+                        "activeDurationS": _number(fields.get("total_timer_time")),
+                        "distanceM": _number(fields.get("distance")),
+                        "strokeCount": _number(fields.get("total_strokes")),
+                        "strokeRate": _number(fields.get("avg_swimming_cadence") or fields.get("avg_cadence")),
+                        "swolf": _number(fields.get("avg_swolf")),
+                        "avgHr": _number(fields.get("avg_heart_rate") or fields.get("average_heart_rate")),
+                        "maxHr": _number(fields.get("max_heart_rate")),
+                        "isRest": length_type in {"rest", "idle", "pause"},
+                        "label": str(fields.get("swim_stroke") or "").lower() or None,
+                        "raw": {name: (value.isoformat().replace("+00:00", "Z") if hasattr(value, "isoformat") else value) for name, value in fields.items()},
+                    }
+                    rows.append(row)
+                return rows
+    except (ImportError, OSError, ValueError, zipfile.BadZipFile):
+        return []
+
+
 def write_parquet(data_dir: Path, activity_id: str, start_date: str, samples: Iterable[dict[str, Any]]) -> tuple[Path, str, int]:
     records = list(samples)
     year, month = (start_date[:4] or "unknown"), (start_date[5:7] or "unknown")