catence 0.2.0-beta.7 → 0.2.0-beta.8

package/README.md

@@ -213,6 +213,34 @@ docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.e
 
 [`config.example.json`](config.example.json) documents rate limits, Strava budgets, and Console model profiles. It intentionally contains environment-variable names rather than credential values. Keep per-athlete provider values in `catence-data secret set`, not in `.env` or `config.json`.
 
+### Per-model reasoning effort
+
+Models that support reasoning effort (e.g., DeepSeek V4 Flash on Opencode Zen) can set it per deployment in `config.json`:
+
+```json
+{
+  "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",
+            "reasoningEffort": "high"
+          }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Supported values: `minimal`, `low`, `medium`, `high` (OpenAI standard). The model-level value overrides any profile-level `defaultReasoningEffort`. If neither is set, the provider default is used.
+
 For source development:
 
 ```sh
@@ -238,3 +266,17 @@ data.
 Garmin is the primary source for activity and wellness data; Intervals.icu supplements training analysis; Strava is used for targeted segments, efforts, and gear. Missing fields mean a provider did not supply a value. The source credentials and source APIs determine the data available. Catence does not use the official Garmin API; Garmin sync relies on the selected athlete’s email/password credentials.
 
 See [distribution notes](docs/distribution.md) for release artifacts, including APM and MCPB demo bundles.
+
+##
+
+```bash
+cd catence-deploy
+docker compose -f docker-compose.yml --env-file .env exec console \
+  catence-data sync --athlete martina --provider all --home /data        # incremental sync, all providers
+docker compose -f docker-compose.yml --env-file .env exec console \
+  catence-data backfill --athlete martina --from 2026-01-01 --home /data # full backfill from a date
+docker compose -f docker-compose.yml --env-file .env exec console \
+  catence-data status --athlete martina --home /data                     # coverage/errors
+docker compose -f docker-compose.yml --env-file .env exec console \
+  catence-data athlete list --home /data                                 # list athlete IDs
+```

package/config.example.json

@@ -44,6 +44,27 @@
         "label": "Anthropic",
         "model": "anthropic/claude-sonnet-4-5",
         "apiKeyEnv": "ANTHROPIC_API_KEY"
+      },
+      "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"
       }
     }
   }

package/dist/contracts/release.d.ts

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export declare const CATENCE_RUNTIME_VERSION = "0.2.0-beta.7";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.0-beta.8";
 export declare const CATENCE_PROTOCOL_VERSION = 1;
 export type CatenceRuntimeCapabilities = {
     mcp: true;

package/dist/contracts/release.js

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export const CATENCE_RUNTIME_VERSION = '0.2.0-beta.7';
+export const CATENCE_RUNTIME_VERSION = '0.2.0-beta.8';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/docs/llm-providers.md

@@ -272,6 +272,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.8",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -29,6 +29,7 @@
     "config.example.json",
     "docs",
     "scripts/discover-opencode-go.mjs",
+    "scripts/discover-opencode-zen.mjs",
     "pyproject.toml",
     "uv.lock",
     "python/__init__.py",
@@ -57,6 +58,7 @@
     "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/scripts/discover-opencode-zen.mjs

@@ -0,0 +1,218 @@
+// Discover OpenCode Zen models and emit Catence Console profiles for them.
+//
+// OpenCode Zen serves its catalog through `GET /v1/models` at
+// `https://opencode.ai/zen/v1`. Models are split between the chat/completions
+// endpoint and the responses endpoint. Routing is determined by model ID prefix:
+// GPT-5.x models use the responses API; everything else uses chat/completions.
+//
+// Usage:
+//   node scripts/discover-opencode-zen.mjs [--base-url <url>] [--write <config.json>] [--set-default] [--free-only]
+//
+// Flags:
+//   --base-url <url>   Root of the OpenCode Zen API (default https://opencode.ai/zen/v1).
+//   --write <path>     Merge the two profiles into an existing config.json instead of printing to stdout.
+//   --set-default      With --write, set console.defaultProfile to opencode-zen even when one already exists.
+//   --free-only        Only include free models (those with -free suffix or known free model IDs).
+
+import process from 'node:process';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const DEFAULT_BASE_URL = 'https://opencode.ai/zen/v1';
+const API_KEY_ENV = 'OPENCODE_API_KEY';
+const API_BASE_ENV = 'OPENCODE_ZEN_API_BASE';
+const RESPONSES_BASE_ENV = 'OPENCODE_ZEN_RESPONSES_API_BASE';
+
+// Models that use the OpenAI Responses API (gpt-5.x series)
+const RESPONSES_PREFIXES = ['gpt-5', 'gpt-5.'];
+
+// Known free model IDs (in case the API doesn't mark them explicitly)
+const KNOWN_FREE_MODELS = new Set([
+  'deepseek-v4-flash-free',
+  'mimo-v2.5-free',
+  'nemotron-3-ultra-free',
+  'nemotron-3.5-lightning-free',
+  'hy3-free',
+  'laguna-s-2.1-free',
+  'big-pickle',
+  'north-mini-code-free',
+  'longcat-2.0-free',
+  'ling-3.0-flash-free',
+  'ling-3.0-tiny-free',
+]);
+
+const BRAND_NAMES = new Map([
+  ['deepseek', 'DeepSeek'],
+  ['gpt', 'GPT'],
+  ['mimo', 'MiMo'],
+  ['nemotron', 'Nemotron'],
+  ['hy3', 'Hy3'],
+  ['laguna', 'Laguna'],
+  ['big', 'Big'],
+  ['pickle', 'Pickle'],
+  ['north', 'North'],
+  ['mini', 'Mini'],
+  ['code', 'Code'],
+  ['longcat', 'LongCat'],
+  ['ling', 'Ling'],
+]);
+
+function isFreeModel(id) {
+  return id.endsWith('-free') || KNOWN_FREE_MODELS.has(id);
+}
+
+function classify(id) {
+  for (const prefix of RESPONSES_PREFIXES) {
+    if (id.startsWith(prefix)) return { route: 'responses', guessed: false };
+  }
+  return { route: 'chat', guessed: false };
+}
+
+function modelReference(id, route) {
+  if (route === 'responses') return `openai/responses/${id}`;
+  return `openai/${id}`;
+}
+
+function labelFor(id) {
+  return id
+    .split('-')
+    .map((segment) => BRAND_NAMES.get(segment) ?? segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join(' ');
+}
+
+function usage() {
+  process.stderr.write(
+    'Usage: node scripts/discover-opencode-zen.mjs [--base-url <url>] [--write <config.json>] [--set-default] [--free-only]\n',
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let baseUrl = DEFAULT_BASE_URL;
+  let writePath = null;
+  let setDefault = false;
+  let freeOnly = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--base-url') {
+      baseUrl = args[i + 1];
+      if (!baseUrl) throw new Error('--base-url requires a URL.');
+      i += 1;
+    } else if (arg === '--write') {
+      writePath = args[i + 1];
+      if (!writePath) throw new Error('--write requires a config.json path.');
+      i += 1;
+    } else if (arg === '--set-default') {
+      setDefault = true;
+    } else if (arg === '--free-only') {
+      freeOnly = true;
+    } else if (arg === '--help' || arg === '-h') {
+      usage();
+      return;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!baseUrl.endsWith('/v1')) {
+    process.stderr.write(`Warning: --base-url ${baseUrl} does not end in /v1; chat and responses URLs may be wrong.\n`);
+  }
+  const modelsUrl = `${baseUrl.replace(/\/$/, '')}/models`;
+
+  let response;
+  try {
+    response = await fetch(modelsUrl, { headers: { accept: 'application/json' } });
+  } catch (error) {
+    throw new Error(`Could not reach ${modelsUrl}: ${error.message}`);
+  }
+  if (!response.ok) {
+    throw new Error(`GET ${modelsUrl} returned HTTP ${response.status}.`);
+  }
+  const payload = await response.json();
+  const ids = (payload.data ?? [])
+    .map((entry) => entry.id)
+    .filter((id) => typeof id === 'string' && id);
+
+  const filteredIds = freeOnly ? ids.filter(isFreeModel) : ids;
+
+  const groups = { chat: [], responses: [] };
+  for (const id of filteredIds) {
+    const { route } = classify(id);
+    if (!(route in groups)) continue;
+    groups[route].push(id);
+  }
+  for (const route of Object.keys(groups)) groups[route].sort();
+
+  const chatProfileModels = {};
+  for (const id of groups.chat) {
+    chatProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'chat') };
+  }
+  const responsesProfileModels = {};
+  for (const id of groups.responses) {
+    responsesProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'responses') };
+  }
+
+  const chatDefault = groups.chat[0];
+  const responsesDefault = groups.responses[0];
+
+  const profiles = {};
+  if (groups.chat.length) {
+    profiles['opencode-zen'] = {
+      label: 'OpenCode Zen',
+      ...(chatDefault ? { defaultModel: chatDefault } : {}),
+      models: chatProfileModels,
+      apiKeyEnv: API_KEY_ENV,
+      apiBaseEnv: API_BASE_ENV,
+    };
+  }
+  if (groups.responses.length) {
+    profiles['opencode-zen-responses'] = {
+      label: 'OpenCode Zen (Responses)',
+      ...(responsesDefault ? { defaultModel: responsesDefault } : {}),
+      models: responsesProfileModels,
+      apiKeyEnv: API_KEY_ENV,
+      apiBaseEnv: RESPONSES_BASE_ENV,
+    };
+  }
+
+  const consoleSection = { defaultProfile: 'opencode-zen', profiles };
+
+  process.stderr.write(
+    `Discovered ${ids.length} models (${groups.chat.length} chat, ${groups.responses.length} responses).` +
+    (freeOnly ? ` Filtered to ${filteredIds.length} free models.` : '') + '\n',
+  );
+
+  if (writePath) {
+    let root = {};
+    try {
+      root = JSON.parse(await readFile(writePath, 'utf8'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw new Error(`Could not read ${writePath}: ${error.message}`);
+    }
+    if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+      throw new Error(`${writePath} must contain a JSON object.`);
+    }
+    const existingConsole = typeof root.console === 'object' && root.console !== null ? root.console : {};
+    const mergedProfiles = { ...(existingConsole.profiles ?? {}), ...profiles };
+    const defaultProfile =
+      existingConsole.defaultProfile && !setDefault ? existingConsole.defaultProfile : 'opencode-zen';
+    root.console = { ...existingConsole, defaultProfile, profiles: mergedProfiles };
+    await writeFile(writePath, `${JSON.stringify(root, null, 2)}\n`);
+    process.stderr.write(`Merged profiles into ${writePath} (defaultProfile: ${defaultProfile}).\n`);
+    return;
+  }
+
+  process.stderr.write(
+    `Export the key and base URLs, then add the JSON below under "console" in config.json:\n` +
+      `  export ${API_KEY_ENV}='sk-…'\n` +
+      `  export ${API_BASE_ENV}='${baseUrl}'\n` +
+      `  export ${RESPONSES_BASE_ENV}='${baseUrl}'\n` +
+      `(or rerun with --write ~/.catence/config.json to merge into an existing config.)\n`,
+  );
+  process.stdout.write(`${JSON.stringify(consoleSection, null, 2)}\n`);
+}
+
+await main().catch((error) => {
+  process.stderr.write(`Error: ${error.message}\n`);
+  process.exit(1);
+});