catence 0.2.0-beta.8 → 0.2.0-beta.9

package/README.md

@@ -215,7 +215,9 @@ docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.e
 
 ### 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`:
+Models that support reasoning effort can set a fixed level per model in `config.json`, or expose a per-chat **Thinking effort** dropdown with custom levels via `variants`.
+
+**Fixed level** (all requests for the model use it):
 
 ```json
 {
@@ -239,7 +241,19 @@ Models that support reasoning effort (e.g., DeepSeek V4 Flash on Opencode Zen) c
 }
 ```
 
-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.
+**Custom variants** (per-chat dropdown): `variants` maps each dropdown label to the value sent to the provider. This is how non-OpenAI models (for example DeepSeek V4 Flash, which uses its own Default/High/Max scheme rather than the OpenAI-standard list) expose their native levels:
+
+```json
+"deepseek-v4-flash-free": {
+  "label": "DeepSeek V4 Flash Free",
+  "model": "openai/deepseek-v4-flash-free",
+  "variants": { "High": "high", "Max": "max" }
+}
+```
+
+With `variants`, the chat **Thinking effort** dropdown shows `Provider default` plus each label; selecting one sends that exact value (e.g. `reasoning_effort: "high"`). Without `variants`, the dropdown falls back to the OpenAI-standard set (`minimal`, `low`, `medium`, `high`, `xhigh`).
+
+A fixed `reasoningEffort` overrides any profile-level `defaultReasoningEffort`; the per-chat dropdown selection (a variant value) overrides both. If nothing is set, the provider default is used.
 
 For source development:
 

package/config.example.json

@@ -49,7 +49,11 @@
         "label": "OpenCode Zen",
         "defaultModel": "deepseek-v4-flash-free",
         "models": {
-          "deepseek-v4-flash-free": { "label": "DeepSeek V4 Flash Free", "model": "openai/deepseek-v4-flash-free" },
+          "deepseek-v4-flash-free": {
+            "label": "DeepSeek V4 Flash Free",
+            "model": "openai/deepseek-v4-flash-free",
+            "variants": { "High": "high", "Max": "max" }
+          },
           "nemotron-3-ultra-free": { "label": "Nemotron 3 Ultra Free", "model": "openai/nemotron-3-ultra-free" },
           "big-pickle": { "label": "Big Pickle", "model": "openai/big-pickle" }
         },

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.8";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.0-beta.9";
 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.8';
+export const CATENCE_RUNTIME_VERSION = '0.2.0-beta.9';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/dist/core/logging.d.ts

@@ -0,0 +1,16 @@
+import type { CatencePaths } from '../contracts/runtime.js';
+export type SyncLogger = {
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, context?: Record<string, unknown>) => void;
+    debug: (message: string, context?: Record<string, unknown>) => void;
+};
+/**
+ * Resolve the sync log file path.
+ *
+ * `CATENCE_LOG` may be an absolute path or a path relative to the catalog home.
+ * When unset (the default), logs go to stderr only so the console stays clean
+ * and stdout remains machine-readable for callers like sync.sh.
+ */
+export declare function resolveLogFile(paths: CatencePaths, environment?: NodeJS.ProcessEnv): string | null;
+export declare function createSyncLogger(paths: CatencePaths, environment?: NodeJS.ProcessEnv): SyncLogger;

package/dist/core/logging.js

@@ -0,0 +1,68 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+const LEVEL_WEIGHT = { debug: 10, info: 20, warn: 30, error: 40 };
+function configuredLevel(environment = process.env) {
+    const raw = (environment.CATENCE_LOG_LEVEL ?? 'info').toLowerCase();
+    if (raw === 'debug')
+        return LEVEL_WEIGHT.debug;
+    if (raw === 'warn')
+        return LEVEL_WEIGHT.warn;
+    if (raw === 'error')
+        return LEVEL_WEIGHT.error;
+    return LEVEL_WEIGHT.info;
+}
+/**
+ * Resolve the sync log file path.
+ *
+ * `CATENCE_LOG` may be an absolute path or a path relative to the catalog home.
+ * When unset (the default), logs go to stderr only so the console stays clean
+ * and stdout remains machine-readable for callers like sync.sh.
+ */
+export function resolveLogFile(paths, environment = process.env) {
+    const configured = environment.CATENCE_LOG;
+    if (!configured)
+        return null;
+    return path.isAbsolute(configured) ? configured : path.join(paths.root, configured);
+}
+export function createSyncLogger(paths, environment = process.env) {
+    const threshold = configuredLevel(environment);
+    const logFile = resolveLogFile(paths, environment);
+    const write = (level, message, context) => {
+        if (LEVEL_WEIGHT[level] < threshold)
+            return;
+        const line = formatLogLine(level, message, context);
+        process.stderr.write(`${line}\n`);
+        if (logFile) {
+            // Fire-and-forget: never block a sync run on log persistence.
+            appendLogLine(logFile, `${line}\n`).catch(() => { });
+        }
+    };
+    return {
+        info: (message, context) => write('info', message, context),
+        warn: (message, context) => write('warn', message, context),
+        error: (message, context) => write('error', message, context),
+        debug: (message, context) => write('debug', message, context),
+    };
+}
+function formatLogLine(level, message, context) {
+    const timestamp = new Date().toISOString();
+    const tag = level.toUpperCase().padEnd(5);
+    let line = `[${timestamp}] [${tag}] ${message}`;
+    if (context && Object.keys(context).length > 0) {
+        line += ` ${serializeContext(context)}`;
+    }
+    return line;
+}
+function serializeContext(context) {
+    try {
+        return JSON.stringify(context);
+    }
+    catch {
+        return '';
+    }
+}
+let appendLogLine = async (file, line) => {
+    await mkdir(path.dirname(file), { recursive: true });
+    await appendFile(file, line, 'utf8');
+};
+//# sourceMappingURL=logging.js.map

package/dist/elt/application/management.js

@@ -8,6 +8,7 @@ import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { buildRetrievalIndex } from '../../core/retrieval/index.js';
 import { defaultFromDate, ensurePaths, requireIntervalsConfig } from '../../core/runtime/configuration.js';
+import { createSyncLogger } from '../../core/logging.js';
 import { athleteProviderEnvironment } from '../../core/runtime/secrets.js';
 import { importJsonl } from '../ingestion/importer.js';
 import { IntervalsExtractor } from '../ingestion/providers/intervals.js';
@@ -19,7 +20,7 @@ const execFileAsync = promisify(execFile);
 function packageRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
 }
-async function syncProvider(database, paths, provider, options) {
+async function syncProvider(database, paths, provider, options, log) {
     const explicitWindow = options.explicitFrom ? { fromDate: options.explicitFrom, toDate: options.toDate, source: 'explicit' } : null;
     const uncoveredExplicitWindow = async (cursorName) => {
         if (!explicitWindow)
@@ -33,6 +34,7 @@ async function syncProvider(database, paths, provider, options) {
     const activityWindow = explicitWindow ? await uncoveredExplicitWindow('activities') : await database.resolveIncrementalWindow(provider, 'activities', options.toDate, defaultFromDate(), 14);
     const hasProviderWork = provider === 'intervals' ? activityWindow !== null : dailyWindow !== null || activityWindow !== null;
     if (!hasProviderWork) {
+        log.debug('No uncovered work; skipping provider', { provider, daily: dailyWindow ?? null, activities: activityWindow ?? null });
         return {
             runId: null, provider, fromDate: null,
             dailyFromDate: dailyWindow?.fromDate ?? null, dailyToDate: dailyWindow?.toDate ?? null,
@@ -43,13 +45,19 @@ async function syncProvider(database, paths, provider, options) {
     }
     const fromDate = [dailyWindow?.fromDate, activityWindow?.fromDate].filter((date) => Boolean(date)).sort()[0];
     const runId = await database.beginRun(provider, fromDate);
+    log.info('Starting sync run', {
+        runId, provider, fromDate, toDate: options.toDate,
+        dailyFrom: dailyWindow?.fromDate ?? null, dailyTo: dailyWindow?.toDate ?? null,
+        activityFrom: activityWindow?.fromDate ?? null, activityTo: activityWindow?.toDate ?? null,
+        backfill: options.backfill, refreshActivities: options.refreshActivities,
+    });
     let extractionStarted = false;
     try {
         if (provider === 'intervals') {
             const environment = await athleteProviderEnvironment(paths);
             const config = requireIntervalsConfig(environment);
             extractionStarted = true;
-            await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
+            await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId, log).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
         }
         else {
             const output = path.join(paths.staging, 'garmin', `${runId}.jsonl`);
@@ -77,14 +85,18 @@ async function syncProvider(database, paths, provider, options) {
             });
             if (!existsSync(output))
                 throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
-            await importJsonl(database, runId, output);
+            await importJsonl(database, runId, output, log);
         }
     }
     catch (error) {
-        await database.addError(runId, provider, 'sync', null, error instanceof Error ? error.message : String(error), true);
+        const message = error instanceof Error ? error.message : String(error);
+        log.error('Sync run failed', { runId, provider, error: message, stack: error instanceof Error ? error.stack : undefined });
+        await database.addError(runId, provider, 'sync', null, message, true);
     }
     finally {
         await database.finishRun(runId);
+        const [run] = await database.rows('SELECT status, error_count FROM sync_runs WHERE run_id = $runId', { runId });
+        log.info('Sync run finished', { runId, provider, status: run?.status ?? 'unknown', errorCount: run?.error_count ?? 0 });
     }
     if (options.advanceCursor && !options.explicitFrom && extractionStarted) {
         await database.advanceIncrementalCursor(provider, 'daily', runId, options.toDate, 3);
@@ -109,12 +121,13 @@ export async function syncData(paths, provider, explicitFrom, advanceCursor = tr
     if (provider === 'strava')
         return { provider, result: await syncStravaGear(paths) };
     const database = await CatenceDatabase.open(paths);
+    const log = createSyncLogger(paths);
     try {
         const providers = provider === 'all' ? ['intervals', 'garmin'] : [provider];
         const toDate = new Date().toISOString().slice(0, 10);
         const runs = [];
         for (const source of providers)
-            runs.push(await syncProvider(database, paths, source, { explicitFrom, toDate, advanceCursor, refreshActivities, backfill }));
+            runs.push(await syncProvider(database, paths, source, { explicitFrom, toDate, advanceCursor, refreshActivities, backfill }, log));
         return { runIds: runs.flatMap((run) => run.runId ? [run.runId] : []), runs };
     }
     finally {
@@ -130,7 +143,8 @@ export async function retryDataSync(paths, previousRunId) {
             throw new Error(`No sync run found for ${previousRunId}.`);
         if (previous.provider === 'strava')
             throw new Error('Retry Strava gear sync with `catence-data sync --provider strava`.');
-        const run = await syncProvider(database, paths, previous.provider, { explicitFrom: previous.from_date, toDate: new Date().toISOString().slice(0, 10), advanceCursor: false, refreshActivities: false, backfill: false });
+        const log = createSyncLogger(paths);
+        const run = await syncProvider(database, paths, previous.provider, { explicitFrom: previous.from_date, toDate: new Date().toISOString().slice(0, 10), advanceCursor: false, refreshActivities: false, backfill: false }, log);
         return { retriedRun: previousRunId, runId: run.runId, run };
     }
     finally {

package/dist/elt/ingestion/importer.d.ts

@@ -1,7 +1,8 @@
 import type { CatenceDatabase } from '../storage/database.js';
 import { type StagingRecord } from '../../contracts/staging.js';
-export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord): Promise<void>;
-export declare function importJsonl(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
+import type { SyncLogger } from '../../core/logging.js';
+export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord, log?: SyncLogger): Promise<void>;
+export declare function importJsonl(database: CatenceDatabase, runId: string, filePath: string, log?: SyncLogger): Promise<number>;
 export declare function importSingleStagingFile(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
 export declare function queueWorkItem(database: CatenceDatabase, runId: string, provider: 'intervals' | 'garmin' | 'strava', endpoint: string, remoteId: string | null, scope: unknown): Promise<string>;
 export declare function completeWorkItem(database: CatenceDatabase, itemId: string): Promise<void>;

package/dist/elt/ingestion/importer.js

@@ -7,7 +7,7 @@ import { importSourceEntity, refreshActivityQuality } from '../normalization/nor
 import { normalizeStravaEntity } from '../normalization/segments/strava-normalizer.js';
 import { reconcileActivityLink } from '../normalization/activities/linking.js';
 import { json } from '../storage/sql.js';
-export async function importRecord(database, runId, record) {
+export async function importRecord(database, runId, record, log) {
     if (record.kind === 'run_manifest') {
         if (record.runId !== runId)
             throw new Error(`Staging manifest run ${record.runId} does not match importer run ${runId}.`);
@@ -54,8 +54,9 @@ export async function importRecord(database, runId, record) {
         return;
     }
     await database.addError(runId, record.provider, record.endpoint, record.remoteId, record.message, record.retryable);
+    log?.warn('Staging record reported an extraction error', { runId, provider: record.provider, endpoint: record.endpoint, remoteId: record.remoteId, error: record.message });
 }
-export async function importJsonl(database, runId, filePath) {
+export async function importJsonl(database, runId, filePath, log) {
     let count = 0;
     const file = createReadStream(filePath, { encoding: 'utf8' });
     const lines = createInterface({ input: file, crlfDelay: Infinity });
@@ -63,7 +64,7 @@ export async function importJsonl(database, runId, filePath) {
         if (!line.trim())
             continue;
         const record = stagingRecordSchema.parse(JSON.parse(line));
-        await importRecord(database, runId, record);
+        await importRecord(database, runId, record, log);
         count += 1;
     }
     return count;

package/dist/elt/ingestion/providers/intervals.d.ts

@@ -1,12 +1,14 @@
 import type { CatenceDatabase } from '../../storage/database.js';
 import type { CatencePaths } from '../../../contracts/runtime.js';
+import type { SyncLogger } from '../../../core/logging.js';
 export declare class IntervalsExtractor {
     private readonly database;
     private readonly paths;
     private readonly apiKey;
     private readonly athleteId;
+    private readonly log;
     private readonly client;
-    constructor(database: CatenceDatabase, paths: CatencePaths, apiKey: string, athleteId: string);
+    constructor(database: CatenceDatabase, paths: CatencePaths, apiKey: string, athleteId: string, log: SyncLogger);
     sync(runId: string, activityWindow: {
         fromDate: string;
         toDate: string;

package/dist/elt/ingestion/providers/intervals.js

@@ -42,12 +42,14 @@ export class IntervalsExtractor {
     paths;
     apiKey;
     athleteId;
+    log;
     client;
-    constructor(database, paths, apiKey, athleteId) {
+    constructor(database, paths, apiKey, athleteId, log) {
         this.database = database;
         this.paths = paths;
         this.apiKey = apiKey;
         this.athleteId = athleteId;
+        this.log = log;
         // The typed client is used for provider-compatible authentication and the
         // primary identity request. Manifest-only calls below intentionally use
         // the same read-only credentials to cover endpoint families not wrapped by it.
@@ -189,6 +191,7 @@ export class IntervalsExtractor {
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             await failWorkItem(this.database, workId, message);
+            this.log.warn('Endpoint capture failed', { runId, provider: 'intervals', endpoint, remoteId, error: message });
             await this.database.addError(runId, 'intervals', endpoint, remoteId, message, true);
             return undefined;
         }

package/dist/elt/ingestion/providers/strava/service.js

@@ -8,6 +8,7 @@ import { ensurePaths, loadCatenceConfig } from '../../../../core/runtime/configu
 import { athleteProviderEnvironment } from '../../../../core/runtime/secrets.js';
 import { CatenceDatabase, openReadOnlyRepository } from '../../../storage/database.js';
 import { importJsonl } from '../../importer.js';
+import { createSyncLogger } from '../../../../core/logging.js';
 import { withDataWriteLock } from '../../../storage/write-lock.js';
 const execFileAsync = promisify(execFile);
 export class StravaRateLimitError extends Error {
@@ -108,6 +109,7 @@ async function cachedState(database, resourceType, remoteId) {
 async function runReadOperation(paths, operation, extraArgs, resource, refresh = false) {
     return withDataWriteLock(paths, async () => {
         await ensurePaths(paths);
+        const log = createSyncLogger(paths);
         const database = await CatenceDatabase.open(paths);
         try {
             if (!refresh) {
@@ -117,6 +119,7 @@ async function runReadOperation(paths, operation, extraArgs, resource, refresh =
             }
             await checkBudget(database, paths);
             const runId = await database.beginRun('strava', new Date().toISOString().slice(0, 10));
+            log.info('Starting Strava read operation', { runId, operation, resource: resource.id });
             const directory = path.join(paths.staging, 'strava');
             const stagingPath = path.join(directory, `${runId}.jsonl`);
             const resultPath = path.join(directory, `${runId}.result.json`);
@@ -124,17 +127,20 @@ async function runReadOperation(paths, operation, extraArgs, resource, refresh =
             try {
                 result = await invokeWorker(paths, ['--mode', operation, '--run-id', runId, '--output', stagingPath, ...extraArgs], resultPath);
                 if (existsSync(stagingPath))
-                    await importJsonl(database, runId, stagingPath);
+                    await importJsonl(database, runId, stagingPath, log);
                 await storeRateState(database, result);
                 await writeState(database, resource.type, resource.id, result);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                log.error('Strava read operation failed', { runId, operation, resource: resource.id, error: message, stack: error instanceof Error ? error.stack : undefined });
                 await database.addError(runId, 'strava', operation, resource.id, message, true);
                 throw error;
             }
             finally {
                 await database.finishRun(runId);
+                const [run] = await database.rows('SELECT status, error_count FROM sync_runs WHERE run_id = $runId', { runId });
+                log.info('Strava read operation finished', { runId, operation, status: run?.status ?? 'unknown', errorCount: run?.error_count ?? 0 });
             }
             if (result.status === 'error')
                 throw new StravaEnrichmentError(result.message ?? 'Strava did not complete the requested enrichment.');

package/dist/elt/storage/database.js

@@ -94,9 +94,11 @@ export class CatenceDatabase {
         const rawObjects = await this.rows('SELECT count(*)::INTEGER AS count FROM raw_objects');
         const activities = await this.rows('SELECT count(*)::INTEGER AS count FROM activities');
         const streams = await this.rows('SELECT count(*)::INTEGER AS count FROM stream_manifest');
+        const errorDetails = await this.rows('SELECT run_id, provider, endpoint, remote_id, message, cast(created_at AS VARCHAR) AS created_at FROM normalization_errors WHERE resolved_at IS NULL ORDER BY created_at DESC LIMIT 100');
         const cursors = await this.rows('SELECT provider, cursor_name, cast(covered_through_date AS VARCHAR) AS covered_through_date, cast(latest_source_date AS VARCHAR) AS latest_source_date, lookback_days, last_successful_run_id, cast(last_completed_at AS VARCHAR) AS last_completed_at, status FROM sync_cursors ORDER BY provider, cursor_name');
         return {
             runs, unresolvedErrors: errors[0]?.count ?? 0, rawObjects: rawObjects[0]?.count ?? 0, activities: activities[0]?.count ?? 0, streams: streams[0]?.count ?? 0,
+            errors: errorDetails,
             cursors: cursors.map((cursor) => ({ ...cursor, next_from_date: subtractDays(cursor.covered_through_date, Number(cursor.lookback_days)) })),
         };
     }

package/docs/llm-providers.md

@@ -373,6 +373,49 @@ 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.
+
+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.
+
 ## Verifying a profile
 
 `catence-console doctor` reports, for each profile, which environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0-beta.8",
+  "version": "0.2.0-beta.9",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {