incremnt 0.4.0 → 0.6.0

package/src/remote.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import { readSnapshot } from './local.js';
-import { executeReadCommand } from './queries.js';
+import { executeCoachReadTool as executeLocalCoachReadTool, executeReadCommand } from './queries.js';
 import { resolveServiceUrl } from './service-url.js';
 
 function notImplementedError() {
@@ -40,7 +40,9 @@ const remoteCommandHandlers = {
   'training-load': executeRemoteRead,
   'ask-history': executeRemoteRead,
   'ask-show': executeRemoteRead,
-  'program-share-fetch': executeRemoteRead
+  'program-share-fetch': executeRemoteRead,
+  'increment-score-current': executeRemoteRead,
+  'increment-score-history': executeRemoteRead
 };
 
 async function executeRemoteRead(options, sessionState, normalizedCommand) {
@@ -161,6 +163,18 @@ function endpointForCommand(baseUrl, normalizedCommand, options) {
       return resolveServiceUrl(baseUrl, `/cli/ask/history/${options.id}`);
     case 'program-share-fetch':
       return resolveServiceUrl(baseUrl, `/program-share/${options.token}`);
+    case 'increment-score-current': {
+      const url = resolveServiceUrl(baseUrl, '/cli/increment-score/current');
+      if (options.historyDays) url.searchParams.set('historyDays', options.historyDays);
+      return url;
+    }
+    case 'increment-score-history': {
+      const url = resolveServiceUrl(baseUrl, '/mobile/score-snapshots');
+      if (options.from) url.searchParams.set('from', options.from);
+      if (options.to) url.searchParams.set('to', options.to);
+      if (options.limit) url.searchParams.set('limit', options.limit);
+      return url;
+    }
     default:
       return resolveServiceUrl(baseUrl, '/');
   }
@@ -190,6 +204,40 @@ function resourceNotFoundMessage(normalizedCommand, options) {
   return 'Requested resource was not found.';
 }
 
+async function executeRemoteCoachReadTool(toolName, input, sessionState) {
+  const baseUrl = sessionState.session?.transport?.baseUrl;
+  if (baseUrl) {
+    const endpoint = resolveServiceUrl(baseUrl, `/cli/coach-tools/${encodeURIComponent(toolName)}`);
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${sessionState.session?.auth?.accessToken ?? ''}`
+      },
+      body: JSON.stringify(input ?? {})
+    });
+
+    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (response.status === 404) {
+      const error = new Error(`Unknown coach read tool: ${toolName}`);
+      error.code = 'REMOTE_NOT_FOUND';
+      throw error;
+    }
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null);
+      const error = new Error(payload?.error ?? `Unexpected error from incremnt sync service (HTTP ${response.status}).`);
+      error.code = 'REMOTE_HTTP_ERROR';
+      throw error;
+    }
+    return response.json();
+  }
+
+  const fixturePath = sessionState.session?.transport?.fixturePath;
+  if (!fixturePath) throw notImplementedError();
+  const snapshot = await readSnapshot(fixturePath);
+  return executeLocalCoachReadTool(snapshot, toolName, input);
+}
+
 const remoteWriteCommandHandlers = {
   'programs-propose': async (options, sessionState) => {
     const baseUrl = sessionState.session?.transport?.baseUrl;
@@ -346,16 +394,54 @@ const remoteWriteCommandHandlers = {
     return response.json();
   },
 
+  'increment-score-upload': async (options, sessionState) => {
+    const baseUrl = sessionState.session?.transport?.baseUrl;
+    if (!baseUrl) throw notImplementedError();
+    if (!options.file) {
+      const error = new Error('--file is required for increment-score upload.');
+      error.code = 'MISSING_OPTION';
+      throw error;
+    }
+
+    const raw = await fs.readFile(options.file, 'utf8');
+    const body = JSON.parse(raw);
+    if (!body || !Array.isArray(body.snapshots)) {
+      const error = new Error('Invalid file: expected an object with a snapshots array.');
+      error.code = 'INVALID_PAYLOAD';
+      throw error;
+    }
+
+    const endpoint = resolveServiceUrl(baseUrl, '/mobile/score-snapshots');
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${sessionState.session?.auth?.accessToken ?? ''}`
+      },
+      body: JSON.stringify(body)
+    });
+
+    if (response.status === 401 || response.status === 403) throw authenticationFailedError();
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null);
+      const error = new Error(payload?.error ?? `Unexpected error (HTTP ${response.status}).`);
+      error.code = 'REMOTE_HTTP_ERROR';
+      throw error;
+    }
+
+    return response.json();
+  },
+
   'program-share-revoke': async (options, sessionState) => {
     const baseUrl = sessionState.session?.transport?.baseUrl;
     if (!baseUrl) throw notImplementedError();
-    if (!options.token) {
-      const error = new Error('--token is required for programs share revoke.');
+    if (!options['share-id']) {
+      const error = new Error('--share-id is required for programs share revoke.');
       error.code = 'MISSING_OPTION';
       throw error;
     }
 
-    const endpoint = resolveServiceUrl(baseUrl, `/cli/program-share/${options.token}/revoke`);
+    const endpoint = resolveServiceUrl(baseUrl, `/cli/program-share/${options['share-id']}/revoke`);
     const response = await fetch(endpoint, {
       method: 'POST',
       headers: {
@@ -365,7 +451,7 @@ const remoteWriteCommandHandlers = {
 
     if (response.status === 401 || response.status === 403) throw authenticationFailedError();
     if (response.status === 404) {
-      const error = new Error(`Program share not found: ${options.token}`);
+      const error = new Error(`Program share not found: ${options['share-id']}`);
       error.code = 'REMOTE_NOT_FOUND';
       throw error;
     }
@@ -407,6 +493,13 @@ export function createRemoteTransport(sessionState, transportOptions = {}) {
 
       return handler(options, sessionState, normalizedCommand);
     },
+    async executeCoachReadTool(toolName, input = {}) {
+      if (transportOptions.expired) {
+        throw expiredSessionError();
+      }
+
+      return executeRemoteCoachReadTool(toolName, input, sessionState);
+    },
     async executeWriteCommand(normalizedCommand, options = {}) {
       if (transportOptions.expired) {
         throw expiredSessionError();

package/src/score-context.js

@@ -0,0 +1,182 @@
+// Derived context for INCREMNT Score snapshots.
+//
+// These fields are computed at response time from existing snapshot data.
+// They are NOT persisted — pure projections of (current snapshot, previous
+// snapshot) into agent-friendly explanatory shape. See GitHub issue #498.
+
+// Score bands. Inclusive lower bound, exclusive upper bound (except 'peak').
+//   0..40   weak
+//   40..60  developing
+//   60..75  solid
+//   75..90  strong
+//   90..100 peak
+export const SCORE_BANDS = [
+  { name: 'weak', min: 0, max: 40 },
+  { name: 'developing', min: 40, max: 60 },
+  { name: 'solid', min: 60, max: 75 },
+  { name: 'strong', min: 75, max: 90 },
+  { name: 'peak', min: 90, max: 101 }
+];
+
+export function computeScoreBand(score) {
+  if (typeof score !== 'number' || !Number.isFinite(score)) return null;
+  for (const band of SCORE_BANDS) {
+    if (score >= band.min && score < band.max) return band.name;
+  }
+  return null;
+}
+
+// Component-keyed action templates surfaced as `recommendedNextActions` for
+// each top-2 negative driver. Keep these short, imperative, single-line.
+const COMPONENT_ACTIONS = {
+  coverage: 'Add the missing muscle groups to your next session to close coverage gaps.',
+  recovery: 'Prioritise sleep and an easier session to let recovery rebound.',
+  stimulus: 'Push closer to productive weekly volume on your lagging muscle groups.',
+  execution: 'Hit your planned sets and reps with cleaner technique next session.',
+  progression: 'Add a small load or rep increase on your main lifts next session.'
+};
+
+const GENERIC_ACTION = 'Address this driver in your next session to lift the score.';
+
+function actionForDriver(driver) {
+  if (!driver || typeof driver !== 'object') return GENERIC_ACTION;
+  const component = typeof driver.component === 'string' ? driver.component : null;
+  if (component && COMPONENT_ACTIONS[component]) {
+    return COMPONENT_ACTIONS[component];
+  }
+  return GENERIC_ACTION;
+}
+
+function driverDisplayMessage(driver) {
+  if (!driver || typeof driver !== 'object') return null;
+  if (typeof driver.message === 'string' && driver.message.trim()) return driver.message;
+  if (typeof driver.label === 'string' && driver.label.trim()) return driver.label;
+  return null;
+}
+
+export function computeRecommendedNextActions(topNegativeDrivers) {
+  if (!Array.isArray(topNegativeDrivers) || topNegativeDrivers.length === 0) return [];
+  return topNegativeDrivers.slice(0, 2).map((driver) => ({
+    component: typeof driver?.component === 'string' ? driver.component : null,
+    driverMessage: driverDisplayMessage(driver),
+    action: actionForDriver(driver)
+  }));
+}
+
+// Top-2 component movers (by absolute change) between current and previous
+// snapshot. Keys present in either side are considered; missing values
+// treated as 0.
+export function computeDeltaDrivers(currentComponents, previousComponents) {
+  if (
+    !currentComponents || typeof currentComponents !== 'object' ||
+    !previousComponents || typeof previousComponents !== 'object'
+  ) {
+    return [];
+  }
+  const keys = new Set([
+    ...Object.keys(currentComponents),
+    ...Object.keys(previousComponents)
+  ]);
+  const moves = [];
+  for (const key of keys) {
+    const cur = Number(currentComponents[key]);
+    const prev = Number(previousComponents[key]);
+    if (!Number.isFinite(cur) && !Number.isFinite(prev)) continue;
+    const c = Number.isFinite(cur) ? cur : 0;
+    const p = Number.isFinite(prev) ? prev : 0;
+    const delta = c - p;
+    if (delta === 0) continue;
+    moves.push({
+      component: key,
+      previousValue: p,
+      currentValue: c,
+      delta: Number(delta.toFixed(2))
+    });
+  }
+  moves.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+  return moves.slice(0, 2);
+}
+
+function formatDelta(delta) {
+  if (delta === null || delta === undefined) return null;
+  if (delta === 0) return 'flat';
+  return delta > 0 ? `up ${delta}` : `down ${Math.abs(delta)}`;
+}
+
+export function computeSummaryText(enriched) {
+  if (!enriched || typeof enriched.score !== 'number') return null;
+  const parts = [];
+  const bandLabel = enriched.scoreBand ? ` (${enriched.scoreBand})` : '';
+  parts.push(`INCREMNT Score ${enriched.score}${bandLabel}.`);
+
+  if (typeof enriched.previousScore === 'number') {
+    const trend = formatDelta(enriched.delta);
+    if (enriched.comparisonSafe) {
+      parts.push(`${trend === 'flat' ? 'Essentially flat' : `Trend ${trend}`} vs previous ${enriched.previousScore}.`);
+    } else {
+      parts.push(`Previous ${enriched.previousScore} (formula version differs or is unavailable, comparison unsafe).`);
+    }
+  } else {
+    parts.push('No prior snapshot for comparison.');
+  }
+
+  const topNeg = Array.isArray(enriched.topNegativeDrivers) ? enriched.topNegativeDrivers[0] : null;
+  const topNegMessage = driverDisplayMessage(topNeg);
+  if (topNegMessage) {
+    parts.push(`Top drag: ${topNegMessage}.`);
+  }
+
+  const firstAction = Array.isArray(enriched.recommendedNextActions) ? enriched.recommendedNextActions[0] : null;
+  if (firstAction && typeof firstAction.action === 'string') {
+    parts.push(`Next: ${firstAction.action}`);
+  }
+
+  return parts.join(' ');
+}
+
+// Enrich an array of snapshots (newest first, as returned by listScoreSnapshots).
+// Adds derived fields to each snapshot in-place via a shallow copy. Existing
+// fields are preserved; only new fields are added.
+export function enrichScoreSnapshots(snapshots) {
+  if (!Array.isArray(snapshots) || snapshots.length === 0) return [];
+  return snapshots.map((snapshot, index) => {
+    const previous = snapshots[index + 1] ?? null;
+    return enrichScoreSnapshot(snapshot, previous);
+  });
+}
+
+export function enrichScoreSnapshot(current, previous) {
+  if (!current || typeof current !== 'object') return current;
+
+  const previousScore = previous && typeof previous.score === 'number' ? previous.score : null;
+  const delta = previousScore !== null && typeof current.score === 'number'
+    ? current.score - previousScore
+    : null;
+
+  const comparisonSafe = !!(
+    previous &&
+    typeof previous.score === 'number' &&
+    typeof current.formulaVersion === 'string' &&
+    typeof previous.formulaVersion === 'string' &&
+    current.formulaVersion === previous.formulaVersion
+  );
+
+  const deltaDrivers = comparisonSafe
+    ? computeDeltaDrivers(current.components, previous.components)
+    : [];
+
+  const scoreBand = computeScoreBand(current.score);
+  const recommendedNextActions = computeRecommendedNextActions(current.topNegativeDrivers);
+
+  const enriched = {
+    ...current,
+    previousScore,
+    delta,
+    comparisonSafe,
+    deltaDrivers,
+    scoreBand,
+    recommendedNextActions
+  };
+  enriched.summaryText = computeSummaryText(enriched);
+  return enriched;
+}

package/src/state.js

@@ -4,12 +4,19 @@ import path from 'node:path';
 
 export const sessionSchemaVersion = 1;
 
+// Prefer HOME env over os.homedir() so test fixtures and explicit overrides
+// work consistently across platforms. On Linux, os.homedir() reads from
+// /etc/passwd via getpwuid and ignores HOME, breaking tests that override HOME.
+export function userHomeDir() {
+  return process.env.HOME || os.homedir();
+}
+
 function fallbackConfigRoot() {
   if (process.platform === 'darwin') {
-    return path.join(os.homedir(), 'Library', 'Application Support');
+    return path.join(userHomeDir(), 'Library', 'Application Support');
   }
 
-  return path.join(os.homedir(), '.config');
+  return path.join(userHomeDir(), '.config');
 }
 
 export function resolveConfigDir() {

package/src/stored-summary-eval-report.js

@@ -1,3 +1,10 @@
+function withPassRate(entry) {
+  return {
+    ...entry,
+    passRate: entry.total > 0 ? entry.passed / entry.total : 0
+  };
+}
+
 export function summarizeResults(results) {
   const counts = {
     total: results.length,
@@ -8,75 +15,85 @@ export function summarizeResults(results) {
   return counts;
 }
 
-export function summarizeBySurface(results) {
+function summarizeByKey(results, keyFn) {
   const grouped = new Map();
   for (const result of results) {
-    const entry = grouped.get(result.surface) ?? { total: 0, passed: 0, failed: 0 };
+    const key = keyFn(result);
+    const entry = grouped.get(key) ?? { total: 0, passed: 0, failed: 0 };
     entry.total += 1;
     if (result.passed) entry.passed += 1;
     else entry.failed += 1;
-    grouped.set(result.surface, entry);
+    grouped.set(key, entry);
   }
 
   return Object.fromEntries(
-    [...grouped.entries()].map(([surface, entry]) => [
-      surface,
-      {
-        ...entry,
-        passRate: entry.total > 0 ? entry.passed / entry.total : 0
-      }
-    ])
+    [...grouped.entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, withPassRate(entry)])
   );
 }
 
-export function buildStoredSummaryReport(snapshotPath, results) {
+export function summarizeBySurface(results) {
+  return summarizeByKey(results, (result) => result.surface);
+}
+
+function normalizeGeneratedDate(generatedAt) {
+  if (typeof generatedAt !== 'string' || generatedAt.trim().length === 0) {
+    return 'legacy';
+  }
+  return generatedAt.slice(0, 10);
+}
+
+function metadataValue(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value : 'legacy';
+}
+
+function summarizeMetadata(results) {
+  return {
+    byPromptVersion: summarizeByKey(results, (result) => metadataValue(result.metadata?.promptVersion)),
+    byModel: summarizeByKey(results, (result) => metadataValue(result.metadata?.model)),
+    byGeneratedDate: summarizeByKey(results, (result) => normalizeGeneratedDate(result.metadata?.generatedAt)),
+    byGitSha: summarizeByKey(results, (result) => metadataValue(result.metadata?.gitSha)),
+    byCohort: summarizeByKey(results, (result) => {
+      const promptVersion = metadataValue(result.metadata?.promptVersion);
+      const model = metadataValue(result.metadata?.model);
+      const generatedDate = normalizeGeneratedDate(result.metadata?.generatedAt);
+      return `${result.surface} / ${promptVersion} / ${model} / ${generatedDate}`;
+    })
+  };
+}
+
+function summarizeStoredResults(results) {
   return {
-    snapshotPath,
     summary: summarizeResults(results),
     bySurface: summarizeBySurface(results),
+    metadata: summarizeMetadata(results)
+  };
+}
+
+export function buildStoredSummaryReport(snapshotPath, results) {
+  const summary = summarizeStoredResults(results);
+  return {
+    snapshotPath,
+    summary: summary.summary,
+    bySurface: summary.bySurface,
+    metadata: summary.metadata,
     results: results.map((result) => ({
       id: result.id,
       surface: result.surface,
       passed: result.passed,
       output: result.output,
+      metadata: result.metadata ?? null,
       failedChecks: result.checks.filter((check) => !check.passed)
     }))
   };
 }
 
 export function summarizeBatchReports(reports) {
-  const bySurface = new Map();
-  let total = 0;
-  let passed = 0;
-
-  for (const report of reports) {
-    total += report.summary.total;
-    passed += report.summary.passed;
-
-    for (const [surface, entry] of Object.entries(report.bySurface ?? {})) {
-      const current = bySurface.get(surface) ?? { total: 0, passed: 0, failed: 0 };
-      current.total += entry.total;
-      current.passed += entry.passed;
-      current.failed += entry.failed;
-      bySurface.set(surface, current);
-    }
-  }
-
+  const results = reports.flatMap((report) => report.results ?? []);
   return {
     snapshotCount: reports.length,
-    total,
-    passed,
-    failed: total - passed,
-    passRate: total > 0 ? passed / total : 0,
-    bySurface: Object.fromEntries(
-      [...bySurface.entries()].map(([surface, entry]) => [
-        surface,
-        {
-          ...entry,
-          passRate: entry.total > 0 ? entry.passed / entry.total : 0
-        }
-      ])
-    )
+    ...summarizeStoredResults(results)
   };
 }
 
@@ -90,8 +107,8 @@ export function evaluateBatchThresholds(summary, {
 } = {}) {
   const failures = [];
 
-  if (typeof minPassRate === 'number' && summary.passRate < minPassRate) {
-    failures.push(`Overall pass rate ${percentage(summary.passRate)} is below required ${percentage(minPassRate)}.`);
+  if (typeof minPassRate === 'number' && summary.summary.passRate < minPassRate) {
+    failures.push(`Overall pass rate ${percentage(summary.summary.passRate)} is below required ${percentage(minPassRate)}.`);
   }
 
   for (const [surface, minimum] of Object.entries(minSurfacePassRates)) {
@@ -105,22 +122,38 @@ export function evaluateBatchThresholds(summary, {
   return failures;
 }
 
+function formatSummaryLines(entries, { limit = null } = {}) {
+  const lines = Object.entries(entries).map(
+    ([label, entry]) => `- ${label}: ${entry.passed}/${entry.total} passed (${(entry.passRate * 100).toFixed(1)}%)`
+  );
+  return limit == null ? lines : lines.slice(0, limit);
+}
+
 export function formatBatchSummaryMarkdown(summary, reports, failures = []) {
   const lines = [
     '# Stored Summary Eval Report',
     '',
     `- Snapshots: ${summary.snapshotCount}`,
-    `- Total summaries: ${summary.total}`,
-    `- Passed: ${summary.passed}`,
-    `- Failed: ${summary.failed}`,
-    `- Pass rate: ${(summary.passRate * 100).toFixed(1)}%`,
+    `- Total summaries: ${summary.summary.total}`,
+    `- Passed: ${summary.summary.passed}`,
+    `- Failed: ${summary.summary.failed}`,
+    `- Pass rate: ${(summary.summary.passRate * 100).toFixed(1)}%`,
     '',
-    '## By Surface'
+    '## By Surface',
+    ...formatSummaryLines(summary.bySurface)
   ];
 
-  for (const [surface, entry] of Object.entries(summary.bySurface)) {
-    lines.push(`- ${surface}: ${entry.passed}/${entry.total} passed (${(entry.passRate * 100).toFixed(1)}%)`);
-  }
+  lines.push('', '## By Prompt Version');
+  lines.push(...formatSummaryLines(summary.metadata.byPromptVersion));
+
+  lines.push('', '## By Model');
+  lines.push(...formatSummaryLines(summary.metadata.byModel));
+
+  lines.push('', '## By Generated Date');
+  lines.push(...formatSummaryLines(summary.metadata.byGeneratedDate));
+
+  lines.push('', '## Versioned Cohorts');
+  lines.push(...formatSummaryLines(summary.metadata.byCohort, { limit: 20 }));
 
   lines.push('', '## Snapshots');
   for (const report of reports) {