Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

27.6 KB
Raw Blame
/**
 * Task Learning — shared persistence layer
 *
 * Owns the on-disk learning data file (load/save with a short-lived in-memory
 * cache), the dismissed-recommendations file, the write mutex, and the small
 * pure helpers (`calculateDurationETA`, `extractTaskType`) that every other
 * taskLearning submodule depends on. Keeping these here avoids circular
 * imports between the metrics / routing / insights modules.
 */

import { join } from 'path';
import { cosEvents, emitLog } from '../cosEvents.js';
import { ensureDir, readJSONFile, PATHS, atomicWrite, tryReadFile } from '../../lib/fileUtils.js';
import { createMutex } from '../../lib/asyncMutex.js';
import { EXTERNAL_UNTYPED_TASK_TYPE, isSandboxedTaskType, classifyUntypedTask, extractTaskType } from '../../lib/taskTypeBucket.js';

export { EXTERNAL_UNTYPED_TASK_TYPE, isSandboxedTaskType, classifyUntypedTask, extractTaskType };

export const withLock = createMutex();

const DATA_DIR = PATHS.cos;
const LEARNING_FILE = join(DATA_DIR, 'learning.json');
export const AGENTS_DIR = join(DATA_DIR, 'agents'); // consumed by metrics.js
const DISMISSED_RECS_FILE = join(DATA_DIR, 'dismissed-recommendations.json');

// Re-export the infra that sibling modules consume so they import from one
// place. (ensureDir / readJSONFile / atomicWrite stay internal to this file.)
export { cosEvents, emitLog, tryReadFile };
export { EXECUTION_EFFORT_NONE, executionKeyPrefix, executionKeyPrefixOf, executionDurationKey } from '../../lib/executionDurationKey.js';

/**
 * Calculate ETA-oriented duration stats from success-only metrics with fallback.
 * Returns { avgDurationMs, maxDurationMs, p80DurationMs }.
 */
export function calculateDurationETA(metrics) {
  const hasSuccessData = (metrics.successDurationMs || 0) > 0;
  const avgBase = hasSuccessData ? metrics.successDurationMs : metrics.totalDurationMs;
  const countBase = hasSuccessData ? metrics.succeeded : metrics.completed;
  if (!countBase || countBase <= 0) return { avgDurationMs: 0, maxDurationMs: 0, p80DurationMs: 0 };
  const avg = Math.round(avgBase / countBase);
  const max = hasSuccessData ? (metrics.successMaxDurationMs || avg) : avg;
  const p80 = Math.round(Math.min(avg * 3, avg + 0.6 * (max - avg)));
  return { avgDurationMs: avg, maxDurationMs: max, p80DurationMs: p80 };
}

// ---------------------------------------------------------------------------
// Execution-scoped duration buckets (issue #8001)
//
// `byTaskType` averages every run of a task type together, so the same
// `self-improve:release-check` on a slow local Ollama model and on a fast cloud
// model land in one bucket and the card's "N min remaining" is wrong for both.
// The provider/model/effort a run actually executed on is the largest single
// driver of its wall-clock time, so `byTaskTypeExecution` keys a second,
// duration-only aggregate by that concrete identity. It is a FLAT map under one
// composed key rather than a 4-level nest: cheaper to prune, iterate and cap.
//
// Duration only — no `recentOutcomes` ring. The LI success-rate signal keeps
// reading `byTaskType`; this dimension exists solely to sharpen the ETA.
// ---------------------------------------------------------------------------

// Ceiling on retained execution buckets. This dimension multiplies task types by
// every provider/model/effort the install has ever run, so the <2-completions/30-day
// prune `byTaskType` gets is not enough on its own — see `saveLearningData`.
export const EXECUTION_BUCKET_CAP = 200;

// ---------------------------------------------------------------------------
// Recent-outcomes ring (issue #2460)
//
// Lifetime `byTaskType` counters (completed/succeeded/failed/successRate) are
// cumulative and never decay, so a burst of since-resolved failures (a provider
// misconfig, PTY-capture artifacts on a now-retired task type) permanently
// depresses the success rate the Layered Intelligence reasoner reads via its
// `cosMetrics` source and keeps signaling "work needed" long after the root cause
// is fixed. To let that signal self-heal WITHOUT destroying the lifetime stats the
// dashboards display, each task-type bucket also carries a bounded ring of recent
// outcomes (`{ t: ISO timestamp, s: success bool }`). `computeWindowedStats`
// derives a recency-windowed success rate from it (bounded by BOTH count and age)
// that LI consumes instead of the lifetime rate. Mirrors the existing
// `failureSignatures.recent` / `recentUnknownErrors` rolling-buffer precedent.
// ---------------------------------------------------------------------------

// Cap on retained recent-outcome samples per task type (oldest pruned first).
export const RECENT_OUTCOMES_CAP = 50;

// Default recency window applied when reading the ring: at most this many
// most-recent runs AND no older than this age. Either bound alone can shrink the
// window; both are overridable per call.
export const DEFAULT_WINDOW_MAX_COUNT = 30;
export const DEFAULT_WINDOW_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days

/**
 * Append a recent outcome to a task-type metrics bucket's bounded ring (issue
 * #2460). Mutates `metrics` in place and returns it for chaining. Stores the compact `{ t, s }`
 * shape (ISO timestamp + success bool), plus `d` (duration ms) when a finite
 * duration was measured — omitted when unknown so a pre-duration sample and a
 * duration-less new sample stay the same shape (absent ≠ 0). Tolerates a bucket
 * that predates the ring (older learning.json before migration 188) by
 * initializing it. Enforces `RECENT_OUTCOMES_CAP`, dropping the oldest sample first.
 */
export function appendRecentOutcome(metrics, { success, at, durationMs } = {}) {
  if (!metrics || typeof metrics !== 'object') return metrics;
  if (!Array.isArray(metrics.recentOutcomes)) metrics.recentOutcomes = [];
  const sample = { t: at || new Date().toISOString(), s: !!success };
  // Only a finite, non-negative duration is a measurement. `|| 0` would collapse
  // "not recorded" into "instant", which is exactly the sentinel the churn
  // detector must not trip on for pre-instrumentation history.
  if (Number.isFinite(durationMs) && durationMs >= 0) sample.d = durationMs;
  metrics.recentOutcomes.push(sample);
  if (metrics.recentOutcomes.length > RECENT_OUTCOMES_CAP) {
    metrics.recentOutcomes = metrics.recentOutcomes.slice(-RECENT_OUTCOMES_CAP);
  }
  return metrics;
}

/**
 * Compute recency-windowed success stats from a task-type recent-outcomes ring
 * (issue #2460). Pure / no I/O. Windows the ring by BOTH a max sample count and a
 * max age, then computes the success rate over just that window.
 *
 * Sentinel discipline (repo "absent vs empty" rule): `windowedSuccessRate` is
 * `null` when the window contains NO samples — never 0 — so a task type with no
 * recent runs is distinguishable from one that recently failed everything. LI
 * falls back to the lifetime rate on null rather than reading a fabricated 0%.
 *
 * @param {Array<{t:string,s:boolean}>} recentOutcomes - the bucket's ring
 * @param {{ maxCount?:number, maxAgeMs?:number, now?:number }} [opts]
 * @returns {{ windowedCompleted:number, windowedSucceeded:number,
 *   windowedFailed:number, windowedSuccessRate:number|null }}
 */
export function computeWindowedStats(recentOutcomes, {
  maxCount = DEFAULT_WINDOW_MAX_COUNT,
  maxAgeMs = DEFAULT_WINDOW_MAX_AGE_MS,
  now = Date.now()
} = {}) {
  const ring = Array.isArray(recentOutcomes) ? recentOutcomes : [];
  const ageCutoff = Number.isFinite(maxAgeMs) && maxAgeMs > 0 ? now - maxAgeMs : null;

  // Age-filter first (drop stale outcomes), then keep only the most-recent
  // `maxCount`. An undated sample (unparseable `t`) is kept — the count bound
  // still applies, so a hand-edited ring can't grow the window unbounded.
  const withinAge = ageCutoff === null
    ? ring
    : ring.filter((o) => {
        const t = Date.parse(o?.t);
        return Number.isFinite(t) ? t >= ageCutoff : true;
      });
  const windowed = Number.isFinite(maxCount) && maxCount > 0
    ? withinAge.slice(-maxCount)
    : withinAge;

  const windowedCompleted = windowed.length;
  const windowedSucceeded = windowed.reduce((n, o) => n + (o?.s ? 1 : 0), 0);
  const windowedFailed = windowedCompleted - windowedSucceeded;
  const windowedSuccessRate = windowedCompleted > 0
    ? Math.round((windowedSucceeded / windowedCompleted) * 100)
    : null;

  return { windowedCompleted, windowedSucceeded, windowedFailed, windowedSuccessRate };
}

// Minimum windowed outcomes before the windowed rate is trusted over the
// lifetime rate (issue #2617). Below this bar the window is too thin to read a
// trend from, so decisions keep today's lifetime behavior (cold-start parity).
export const EFFECTIVE_RATE_MIN_WINDOW_SAMPLES = 5;

/**
 * Effective success rate for DECISION paths (issue #2617). Pure / no I/O.
 *
 * Lifetime `successRate` never decays, so a burst of since-fixed failures
 * permanently depresses it — cooldown/skip/approval decisions built on it keep
 * punishing a task type long after it recovered. This returns the recency-
 * windowed rate (`computeWindowedStats` over the bucket's `recentOutcomes`
 * ring) whenever the window holds at least `minWindowSamples` outcomes, and
 * falls back to the lifetime rate otherwise — so a type with a thin/empty
 * window behaves exactly as before, while a type with a healthy recent record
 * recovers as soon as it starts succeeding again.
 *
 * Sentinel discipline: `successRate` is `null` (never a fabricated 0) when the
 * fallback lifetime rate is itself absent. `source` names which rate was used
 * (`'windowed'` | `'lifetime'`) so decisions can surface it in reasons/logs.
 *
 * @param {Object|null|undefined} metrics - a `byTaskType` bucket
 * @param {{ minWindowSamples?:number, maxCount?:number, maxAgeMs?:number, now?:number }} [opts]
 *   - extra keys are forwarded to `computeWindowedStats` (window bounds/clock seam)
 * @returns {{ successRate:number|null, source:'windowed'|'lifetime', windowedCompleted:number }}
 */
export function computeEffectiveSuccessRate(metrics, opts = {}) {
  const { minWindowSamples = EFFECTIVE_RATE_MIN_WINDOW_SAMPLES } = opts;
  const { windowedCompleted, windowedSuccessRate } = computeWindowedStats(metrics?.recentOutcomes, opts);
  if (windowedSuccessRate !== null && windowedCompleted >= minWindowSamples) {
    return { successRate: windowedSuccessRate, source: 'windowed', windowedCompleted };
  }
  return { successRate: metrics?.successRate ?? null, source: 'lifetime', windowedCompleted };
}

/**
 * Shared skip predicate (issue #2617): a task type is a skip candidate when it
 * has ≥5 lifetime completions AND its EFFECTIVE success rate is <30%. Pure.
 *
 * This is THE definition of "skipped" — used by the scheduling decision
 * (`getAdaptiveCooldownMultiplier`'s skip branch mirrors it), the skip list
 * (`getSkippedTaskTypes`), the rehabilitation/status views, AND the health
 * summaries (`getPerformanceSummary`, `getLearningSummary`). Keeping every
 * consumer on one predicate is what stops a dashboard/alert surface from
 * claiming a type is skipped after the actual decision path stopped skipping
 * it (or vice versa).
 */
export function isSkipCandidate(metrics) {
  if (!metrics || (metrics.completed ?? 0) < 5) return false;
  const { successRate } = computeEffectiveSuccessRate(metrics);
  return successRate !== null && successRate < 30;
}

/**
 * Default learning data structure
 */
// Environmental/infrastructure error categories (issue #2618): failures that say
// nothing about the task or the model — a provider outage, an exhausted quota, a
// revoked key, a dead network, an agent that never started. These are EXCLUDED
// from the success-rate aggregates (`byTaskType` / `byModelTier` /
// `routingAccuracy` / `totals` / the `recentOutcomes` windowed ring / the
// correlation window) so an hour of provider 529s can't crater a task type's
// rate, steer routing off a healthy tier, or trip the <30% skip gate. They are
// instead counted in `data.environmentalFailures[category]` (count +
// lastOccurred + affected task types) so the events stay visible, and they STILL
// feed `errorPatterns` / `failureSignatures` — prompt recommendations and
// diagnostics appropriately consume those.
//
// Covers BOTH classifier vocabularies that can stamp `errorAnalysis.category`:
// agentErrorAnalysis's ERROR_PATTERNS (`rate-limit`, `usage-limit`, `auth-error`,
// `forbidden`, `billing-error`, `network-error`, `claude-error` —
// `overloaded_error`, `startup-failure`, `model-not-found`,
// `model-not-supported`) and agentRunTracking's extractErrorFromOutput (`auth`,
// `connection`, `rate-limit`). `model-not-available` is the legacy naming for
// the model-unavailability class (still present in stored learning data /
// prompt insights).
//
// Deliberately EXCLUDES `timeout`, `unknown`, `process-killed`, and the generic
// `api-error`: each can be genuine task/model signal (a task too big for its
// tier times out or blows resource limits; an uncategorized or generic API
// failure may be anything, including a task-induced bad request). Also EXCLUDES
// the mixed-provenance categories `server-error` and `spawn-error`: their
// classifier regexes (`/server error|internal error/`, `command not found`)
// match ordinary task output too — a genuinely failing app test printing
// "Internal Server Error" must keep denting the rate, not vanish as an
// "outage". Superset of agentErrorAnalysis's `API_ACCESS_ERROR_CATEGORIES`
// (auth-error / forbidden / usage-limit — asserted by a cross-check test in
// agentErrorAnalysis.test.js) but defined here as its own leaf constant:
// importing agentErrorAnalysis.js would drag the cos.js task-store graph into
// every taskLearning consumer and suite.
export const ENVIRONMENTAL_ERROR_CATEGORIES = new Set([
  'rate-limit',
  'usage-limit',
  'auth-error',
  'auth',
  'forbidden',
  'billing-error',
  'connection',
  'network-error',
  // #3358: a PR-shaped run finalized while `gh` could not reach the forge. The
  // run itself may have been perfect — we simply could not confirm its PR — so
  // it must not dent the type's success rate the way `pr-missing` (the agent's
  // own miss, deliberately NOT listed here) should.
  'forge-unreachable',
  'claude-error',
  'startup-failure',
  'model-not-available',
  'model-not-found',
  'model-not-supported',
  // The provider CLI never started — its config file was invalid. Nothing about
  // the task itself failed, so it must not dent the task type's success rate.
  'cli-config-invalid'
]);

const DEFAULT_LEARNING_DATA = {
  // v2 (issue #2460): each byTaskType bucket carries a bounded `recentOutcomes`
  // ring so the signal LI reads can be recency-windowed (see appendRecentOutcome
  // / computeWindowedStats below). Migration 188 initializes the ring on existing
  // installs; fresh installs seed at v2.
  version: 2,
  lastUpdated: null,

  // Metrics by self-improvement task type
  byTaskType: {},

  // Duration-only metrics by task type × the concrete execution identity the run
  // used (issue #8001) — a flat map keyed by `executionDurationKey`. Additive:
  // older learning.json files predate this key and load fine; the recording path
  // initializes it on first use, exactly as `failureSignatures` /
  // `environmentalFailures` / `correlationWindow` did. Bounded by the prune +
  // EXECUTION_BUCKET_CAP sweep in `saveLearningData`.
  byTaskTypeExecution: {},

  // Metrics by model tier
  byModelTier: {},

  // Metrics by error category
  errorPatterns: {},

  // Structured failure signatures by error category (issue #2329): each entry
  // aggregates enriched telemetry — recent messageSnippet/failurePosition plus
  // the execution context (provider/model/tier) and latency of failures in that
  // category. Additive: older learning.json files predate this key and load fine.
  failureSignatures: {},

  // Routing accuracy: taskType → modelTier → { succeeded, failed }
  // Records which model tiers work/fail for each task type
  routingAccuracy: {},

  // Environmental/infrastructure failures (issue #2618): category →
  // { count, lastOccurred, taskTypes } for rate-limit/auth/billing/startup-class
  // failures, which are kept OUT of every success-rate aggregate above so an
  // outage can't poison routing/skip decisions (see ENVIRONMENTAL_ERROR_CATEGORIES
  // in metrics.js). Additive: older learning.json files predate this key and load
  // fine — the recording path initializes it on first use.
  environmentalFailures: {},

  // Rolling correlation-quality window (issue #2344): prediction/outcome pairs
  // measuring how well the enriched failure signals predict actual outcomes.
  // Gates auto-adjustment aggressiveness (see correlationQuality.js). Additive:
  // older learning.json files predate this key and load fine.
  correlationWindow: [],

  // Overall stats
  totals: {
    completed: 0,
    succeeded: 0,
    failed: 0,
    totalDurationMs: 0,
    avgDurationMs: 0
  }
};

// In-memory cache for learning data — avoids redundant disk reads during
// evaluation cycles where multiple functions read the same file.
let _learningCache = null;
let _learningCacheTime = 0;
const LEARNING_CACHE_TTL_MS = 5000;

/**
 * Clear the learning data cache. Exposed for testing.
 */
export function clearLearningCache() {
  _learningCache = null;
  _learningCacheTime = 0;
}

/**
 * Load learning data from file (cached for 5s)
 */
export async function loadLearningData() {
  if (_learningCache && (Date.now() - _learningCacheTime) < LEARNING_CACHE_TTL_MS) {
    return structuredClone(_learningCache);
  }

  await ensureDir(DATA_DIR);

  // Strict (#4115): every mutation is `loadLearningData → mutate →
  // saveLearningData`, so a swallowed unreadable file hands the caller a fresh
  // DEFAULT_LEARNING_DATA and the next save atomicWrites it over the whole
  // routing/outcome history. It also feeds the CoS learning counts. Throwing
  // skips the cycle and leaves the file intact.
  const data = await readJSONFile(LEARNING_FILE, structuredClone(DEFAULT_LEARNING_DATA), { strict: true });
  _learningCache = structuredClone(data);
  _learningCacheTime = Date.now();
  return data;
}

// Ledger of agent ids already folded into the aggregates (#13095). Both the live
// `agent:completed` listener and `backfillFromHistory` feed `recordTaskCompletion`,
// so the ledger lives beside the metrics it protects and is checked under the same
// lock. Bounded FIFO: ids are short, and the newest runs are the ones a repeated
// backfill or a replayed completion can plausibly re-present.
export const COUNTED_AGENT_IDS_CAP = 10000;

export function hasCountedAgent(data, agentId) {
  return !!agentId && Array.isArray(data.countedAgentIds) && data.countedAgentIds.includes(agentId);
}

export function markAgentCounted(data, agentId) {
  if (!agentId) return;
  if (!Array.isArray(data.countedAgentIds)) data.countedAgentIds = [];
  data.countedAgentIds.push(agentId);
  if (data.countedAgentIds.length > COUNTED_AGENT_IDS_CAP) {
    data.countedAgentIds = data.countedAgentIds.slice(-COUNTED_AGENT_IDS_CAP);
  }
}

/**
 * Save learning data to file
 */
export async function saveLearningData(data) {
  data.lastUpdated = new Date().toISOString();

  // Prune task types with fewer than 2 completions and last seen > 30 days ago
  const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
  const isStaleThinBucket = (stats) =>
    (stats?.completed || 0) < 2 && stats?.lastCompleted && new Date(stats.lastCompleted).getTime() < cutoff;
  if (data.byTaskType) {
    for (const [type, stats] of Object.entries(data.byTaskType)) {
      if (isStaleThinBucket(stats)) delete data.byTaskType[type];
    }
  }

  // Same prune for the execution dimension (issue #8001), plus a hard cap: this
  // map is task types MULTIPLIED by every provider/model/effort the install has
  // run, so the thin/stale sweep alone can't bound it — a long-lived install that
  // keeps switching models would accumulate a bucket per combination forever.
  // Over the cap, the least-recently-completed buckets go first: they are the ones
  // whose estimate is least likely to describe how the install runs today.
  if (data.byTaskTypeExecution) {
    for (const [key, stats] of Object.entries(data.byTaskTypeExecution)) {
      if (isStaleThinBucket(stats)) delete data.byTaskTypeExecution[key];
    }
    const keys = Object.keys(data.byTaskTypeExecution);
    if (keys.length > EXECUTION_BUCKET_CAP) {
      // An undated bucket sorts oldest (0) — it carries no evidence of recency,
      // so it is the first thing to give up when the map is over budget.
      const byRecency = keys.sort((a, b) => (
        (Date.parse(data.byTaskTypeExecution[a]?.lastCompleted) || 0)
        - (Date.parse(data.byTaskTypeExecution[b]?.lastCompleted) || 0)
      ));
      for (const key of byRecency.slice(0, keys.length - EXECUTION_BUCKET_CAP)) {
        delete data.byTaskTypeExecution[key];
      }
    }
  }

  await atomicWrite(LEARNING_FILE, data);
  _learningCache = structuredClone(data);
  _learningCacheTime = Date.now();
  cosEvents.emit('goals:changed', {});
  cosEvents.emit('learning:changed');
}

/**
 * Summarize the enriched `failureSignatures` map (issues #2329/#2333) into a
 * ranked, display-ready list. Reads each category's `recent[]` samples to add
 * provider/model attribution and success-criteria (validation) miss counts that
 * the coarser `errorPatterns` aggregate can't express — so the self-improvement
 * loop (insights + prompt recommendations) can say WHICH provider/model recently
 * failed for a task type, not just how often a category occurred.
 *
 * Pure / read-only. When `taskType` is given, only samples recorded for that
 * task type count (and categories with no matching sample are dropped) so a
 * per-type recommendation never inherits another type's failures.
 *
 * @param {Object} failureSignatures - `data.failureSignatures`: `{ [category]: { count, lastOccurred, recent: [] } }`
 * @param {Object} [opts]
 * @param {string|null} [opts.taskType] - restrict samples to this task type
 * @param {number} [opts.limit] - max categories returned (ranked by count desc)
 * @returns {Array<{category, count, samples, lastOccurred, providers, validationMissed, sampleSnippet}>}
 */
export function summarizeFailureSignatures(failureSignatures, { taskType = null, limit = 5 } = {}) {
  const map = failureSignatures && typeof failureSignatures === 'object' ? failureSignatures : {};
  const summaries = [];

  for (const [category, bucket] of Object.entries(map)) {
    const recent = Array.isArray(bucket?.recent) ? bucket.recent : [];
    const matched = taskType ? recent.filter((s) => s?.taskType === taskType) : recent;
    // Task-type-scoped view drops categories with no sample for that type.
    if (taskType && matched.length === 0) continue;

    const attribution = new Map();
    let validationMissed = 0;
    for (const s of matched) {
      const key = s?.provider
        ? `${s.provider}${s.model ? `/${s.model}` : ''}`
        : (s?.modelTier || 'unknown');
      attribution.set(key, (attribution.get(key) || 0) + 1);
      // Explicit === false so an absent/undefined criterion (null) isn't a miss.
      if (s?.validationPassed === false) validationMissed++;
    }

    const providers = [...attribution.entries()]
      .map(([key, count]) => ({ key, count }))
      .sort((a, b) => b.count - a.count);
    const latest = matched.length ? matched[matched.length - 1] : null;

    summaries.push({
      category,
      // Per-type count reflects the matched samples; the global view prefers the
      // lifetime `count` (recent[] is capped) and falls back to the sample size.
      count: taskType ? matched.length : (Number(bucket?.count) || matched.length),
      samples: matched.length,
      lastOccurred: bucket?.lastOccurred || latest?.recordedAt || null,
      providers,
      validationMissed,
      sampleSnippet: latest?.messageSnippet || null
    });
  }

  return summaries.sort((a, b) => b.count - a.count).slice(0, Math.max(0, limit));
}

// ---------------------------------------------------------------------------
// Human-readable insights (issue #2443)
//
// The insights array is the ONE prose channel in the learning store: standing
// "operating notes" the user reads in the CoS UI. It is runtime data in
// `data/cos/learning.json` — never committed to git and never federated — so
// auto-recorded insight text must stay free of hostnames/paths/PII (build it
// only from controlled labels: error category, counts, task type, provider/model
// ids, agent id — never the raw error message, which can embed a path).
// ---------------------------------------------------------------------------

// Cap on retained insights (oldest pruned first). Matches the pre-existing cap
// that `recordLearningInsight` enforced before it was factored out here.
export const INSIGHT_CAP = 50;

// Recurrence counts (of a single error category) at which the failure path
// auto-records a standing insight. Exact-equality matching over these ascending
// milestones makes recording idempotent — the per-category count only increments
// by one per categorized failure, so each milestone fires exactly once and then
// escalates, rather than spamming an insight on every subsequent failure.
export const RECURRENCE_INSIGHT_MILESTONES = [3, 10, 25, 50, 100];

/** True when a category's post-increment recurrence count lands on a milestone. */
export function recurrenceMilestoneReached(count) {
  return RECURRENCE_INSIGHT_MILESTONES.includes(count);
}

/**
 * Append an insight to `data.insights`, stamping `recordedAt` and defaulting
 * `origin` to `'user'` (a manual API insight) unless the caller marks it
 * `'auto-incident'`. Pure over `data` (mutates + returns it); enforces the
 * `INSIGHT_CAP` (oldest pruned). Shared by the manual route (`recordLearningInsight`)
 * and the failure-path auto-recorder so both stay in one shape.
 */
export function appendInsight(data, insight) {
  if (!Array.isArray(data.insights)) data.insights = [];
  data.insights.push({ origin: 'user', ...insight, recordedAt: new Date().toISOString() });
  if (data.insights.length > INSIGHT_CAP) {
    data.insights = data.insights.slice(-INSIGHT_CAP);
  }
  return data;
}

/**
 * Build a provenance-stamped, privacy-safe insight for a recurring failure
 * category (issue #2443). Pure — no I/O. Uses only controlled fields (category
 * label, recurrence count, task type, provider/model ids, agent id); it reads
 * the enriched `failureSignatures` map for provider/model attribution but never
 * echoes the raw error message (which can embed a path/PII). `origin` is
 * `'auto-incident'` so the UI can distinguish it from user-authored notes.
 */
export function buildRecurrenceInsight({ category, count, taskType, agentId = null, failureSignatures = {} } = {}) {
  const summary = summarizeFailureSignatures(failureSignatures, { taskType })
    .find((s) => s.category === category);
  const topProvider = summary?.providers?.[0]?.key || null;
  const via = topProvider ? `, most recently via ${topProvider}` : '';
  const message = `Recurring failure: "${category}" errors have occurred ${count} times for ${taskType} tasks${via}. Auto-flagged at ${count} occurrences — investigate the root cause or route this task type away from the failing path.`;

  return {
    type: 'recurring-failure',
    origin: 'auto-incident',
    category,
    taskType,
    recurrenceCount: count,
    provider: topProvider,
    originatingAgentId: agentId,
    message
  };
}

/**
 * Load dismissed recommendations map: { [id]: { dismissedAt, snapshot } }
 */
export async function loadDismissedRecommendations() {
  await ensureDir(DATA_DIR);
  // Strict (#4115): `dismissRecommendation` / `restoreRecommendation` load this
  // map, mutate one key, and write the whole thing back — an unreadable file
  // would silently un-dismiss every recommendation on the next dismissal.
  return await readJSONFile(DISMISSED_RECS_FILE, {}, { strict: true });
}

export async function saveDismissedRecommendations(map) {
  await atomicWrite(DISMISSED_RECS_FILE, map);
}