rlhf-feedback-loop 0.6.10 → 0.6.12

package/scripts/prove-intelligence.js

@@ -15,7 +15,9 @@ const path = require('path');
 const { execSync } = require('child_process');
 
 const ROOT = path.join(__dirname, '..');
-const PROOF_DIR = path.join(ROOT, 'proof');
+function getProofDir() {
+  return process.env.RLHF_PROOF_DIR || path.join(ROOT, 'proof');
+}
 
 function ensureDir(d) {
   if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
@@ -185,9 +187,10 @@ async function main() {
     overallPassed: allPassed,
   };
 
-  ensureDir(PROOF_DIR);
-  const jsonPath = path.join(PROOF_DIR, 'intelligence-report.json');
-  const mdPath = path.join(PROOF_DIR, 'intelligence-report.md');
+  const proofDir = getProofDir();
+  ensureDir(proofDir);
+  const jsonPath = path.join(proofDir, 'intelligence-report.json');
+  const mdPath = path.join(proofDir, 'intelligence-report.md');
 
   fs.writeFileSync(jsonPath, JSON.stringify(report, null, 2));
 

package/scripts/prove-lancedb.js

@@ -18,7 +18,6 @@ const os = require('os');
 const { execSync } = require('child_process');
 
 const ROOT = path.join(__dirname, '..');
-const PROOF_DIR = path.join(ROOT, 'proof');
 const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));
 
 function ensureDir(dirPath) {
@@ -31,7 +30,8 @@ function status(condition) {
   return condition ? 'pass' : 'fail';
 }
 
-async function runProof() {
+async function runProof(options = {}) {
+  const proofDir = options.proofDir || process.env.RLHF_PROOF_DIR || path.join(ROOT, 'proof');
   const report = {
     phase: '04-lancedb-vector-storage',
     generated: new Date().toISOString(),
@@ -228,7 +228,7 @@ async function runProof() {
   } finally {
     // Clean up tmp dir
     try {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
+      fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
     } catch (_) {
       // ignore cleanup errors
     }
@@ -295,9 +295,9 @@ async function runProof() {
   // ─────────────────────────────────────────────────────────────────────────
   // Write proof artifacts
   // ─────────────────────────────────────────────────────────────────────────
-  ensureDir(PROOF_DIR);
+  ensureDir(proofDir);
 
-  const jsonPath = path.join(PROOF_DIR, 'lancedb-report.json');
+  const jsonPath = path.join(proofDir, 'lancedb-report.json');
   fs.writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`);
 
   const mdLines = [
@@ -341,7 +341,7 @@ async function runProof() {
   mdLines.push('- multi-upsert top-k includes expected record');
   mdLines.push('');
 
-  const mdPath = path.join(PROOF_DIR, 'lancedb-report.md');
+  const mdPath = path.join(proofDir, 'lancedb-report.md');
   fs.writeFileSync(mdPath, `${mdLines.join('\n')}\n`);
 
   console.log(`Proof written to ${mdPath}`);
@@ -352,7 +352,7 @@ async function runProof() {
   const hasFail = report.summary.failed > 0;
   if (hasFail) {
     process.exitCode = 1;
-    console.error('\nFAIL — one or more requirements did not pass. See proof/lancedb-report.md for details.');
+    console.error(`\nFAIL — one or more requirements did not pass. See ${mdPath} for details.`);
   } else {
     console.log('\nPASS — all requirements satisfied (warns are acceptable).');
   }

package/scripts/prove-local-intelligence.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..');
+const DEFAULT_PROOF_DIR = process.env.RLHF_PROOF_DIR || path.join(ROOT, 'proof');
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function runTests() {
+  try {
+    return execSync(
+      'node --test tests/local-model-profile.test.js tests/risk-scorer.test.js tests/vector-store.test.js tests/feedback-sequences.test.js tests/feedback-loop.test.js',
+      { cwd: ROOT, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+  } catch (err) {
+    return err.stdout || err.stderr || String(err);
+  }
+}
+
+function parseTestOutput(output) {
+  const passMatch = output.match(/ℹ pass (\d+)/);
+  const failMatch = output.match(/ℹ fail (\d+)/);
+  return {
+    passed: passMatch ? Number(passMatch[1]) : 0,
+    failed: failMatch ? Number(failMatch[1]) : 0,
+  };
+}
+
+async function main() {
+  const output = runTests();
+  const testResults = parseTestOutput(output);
+  const proofDir = DEFAULT_PROOF_DIR;
+  ensureDir(proofDir);
+
+  const tmpFeedbackDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rlhf-local-intel-'));
+  const report = {
+    generatedAt: new Date().toISOString(),
+    checks: [],
+    summary: { passed: 0, failed: 0 },
+    testResults,
+  };
+
+  function addResult(id, passed, evidence) {
+    report.checks.push({ id, passed, evidence });
+    if (passed) report.summary.passed += 1;
+    else report.summary.failed += 1;
+  }
+
+  try {
+    const { writeModelFitReport } = require('./local-model-profile');
+    const { reportPath, report: modelFitReport } = writeModelFitReport(tmpFeedbackDir, {
+      resolved: require('./local-model-profile').resolveEmbeddingProfile({
+        RLHF_RAM_BYTES_OVERRIDE: String(4 * 1024 ** 3),
+        RLHF_CPU_COUNT_OVERRIDE: '4',
+      }),
+    });
+    addResult(
+      'FIT-01',
+      fs.existsSync(reportPath) && modelFitReport.selectedProfile.id === 'compact',
+      `model-fit report written; selected profile=${modelFitReport.selectedProfile.id}; maxChars=${modelFitReport.selectedProfile.maxChars}`
+    );
+
+    process.env.RLHF_FEEDBACK_DIR = tmpFeedbackDir;
+    process.env.RLHF_MODEL_FIT_PROFILE = 'quality';
+    process.env.RLHF_VECTOR_FORCE_PRIMARY_FAILURE = 'true';
+    delete process.env.RLHF_VECTOR_STUB_EMBED;
+    delete require.cache[require.resolve('./vector-store')];
+    const vectorStore = require('./vector-store');
+    vectorStore.setLanceLoaderForTests(async () => {
+      const tables = new Map();
+      return {
+        connect: async () => ({
+          tableNames: async () => [...tables.keys()],
+          openTable: async (name) => {
+            const rows = tables.get(name) || [];
+            return {
+              add: async (records) => {
+                rows.push(...records);
+                tables.set(name, rows);
+              },
+              search: () => ({
+                limit: (limit) => ({
+                  toArray: async () => rows.slice(0, limit),
+                }),
+              }),
+            };
+          },
+          createTable: async (name, records) => {
+            tables.set(name, [...records]);
+            return {
+              add: async (more) => {
+                const rows = tables.get(name) || [];
+                rows.push(...more);
+                tables.set(name, rows);
+              },
+            };
+          },
+        }),
+      };
+    });
+    vectorStore.setPipelineLoaderForTests(async (_task, model, opts) => async () => ({
+      data: Float32Array.from({ length: 384 }, (_, index) => (index === 0 ? 1 : 0)),
+      model,
+      opts,
+    }));
+    await vectorStore.upsertFeedback({
+      id: 'proof-local-intel',
+      signal: 'positive',
+      context: 'vector fallback proof',
+      tags: ['proof'],
+      timestamp: new Date().toISOString(),
+    });
+    const fallbackProfile = vectorStore.getLastEmbeddingProfile();
+    addResult(
+      'FIT-02',
+      Boolean(fallbackProfile && fallbackProfile.fallbackUsed),
+      `vector-store active profile=${fallbackProfile && fallbackProfile.activeProfile ? fallbackProfile.activeProfile.id : 'none'}; fallbackUsed=${fallbackProfile ? fallbackProfile.fallbackUsed : false}; reason=${fallbackProfile ? fallbackProfile.fallbackReason : 'n/a'}`
+    );
+
+    delete require.cache[require.resolve('./feedback-loop')];
+    const { captureFeedback, analyzeFeedback } = require('./feedback-loop');
+    captureFeedback({
+      signal: 'up',
+      context: 'ran tests and included logs',
+      whatWorked: 'verification complete',
+      tags: ['testing', 'verification'],
+    });
+    captureFeedback({
+      signal: 'down',
+      context: 'skipped tests and missing logs caused failure',
+      whatWentWrong: 'verification skipped',
+      whatToChange: 'always run tests',
+      tags: ['debugging', 'verification'],
+    });
+    captureFeedback({
+      signal: 'up',
+      context: 'proof attached and verification complete',
+      whatWorked: 'full evidence',
+      tags: ['testing', 'verification'],
+    });
+    captureFeedback({
+      signal: 'down',
+      context: 'unsafe path and security risk caused rejection',
+      whatWentWrong: 'unsafe path',
+      whatToChange: 'validate paths',
+      tags: ['security'],
+    });
+    const clarification = captureFeedback({
+      signal: 'up',
+      context: 'thumbs up',
+      tags: ['verification'],
+    });
+    addResult(
+      'VETO-01',
+      clarification.status === 'clarification_required' && clarification.needsClarification === true,
+      `vague feedback status=${clarification.status}; prompt=${clarification.prompt || 'n/a'}`
+    );
+    captureFeedback({
+      signal: 'positive',
+      context: 'claimed success without logs',
+      whatWorked: 'Reviewer approved despite missing logs',
+      tags: ['verification'],
+      rubricScores: [
+        { criterion: 'verification_evidence', score: 5, judge: 'judge-a' },
+        { criterion: 'verification_evidence', score: 2, judge: 'judge-b', evidence: 'missing logs' },
+      ],
+      guardrails: {
+        testsPassed: false,
+        pathSafety: true,
+        budgetCompliant: true,
+      },
+    });
+    captureFeedback({
+      signal: 'down',
+      context: 'regression due to skipped verification',
+      whatWentWrong: 'regression shipped',
+      whatToChange: 'add regression tests',
+      tags: ['debugging', 'verification'],
+    });
+
+    const riskModelPath = path.join(tmpFeedbackDir, 'risk-model.json');
+    const analysis = analyzeFeedback();
+    addResult(
+      'RISK-01',
+      fs.existsSync(riskModelPath),
+      'risk-model artifact written'
+    );
+    addResult(
+      'RISK-02',
+      Boolean(analysis.boostedRisk && analysis.boostedRisk.exampleCount >= 6),
+      `boostedRisk exampleCount=${analysis.boostedRisk ? analysis.boostedRisk.exampleCount : 0}; mode=${analysis.boostedRisk ? analysis.boostedRisk.mode : 'none'}; topDomain=${analysis.boostedRisk && analysis.boostedRisk.highRiskDomains[0] ? analysis.boostedRisk.highRiskDomains[0].key : 'none'}`
+    );
+  } finally {
+    delete process.env.RLHF_FEEDBACK_DIR;
+    delete process.env.RLHF_MODEL_FIT_PROFILE;
+    delete process.env.RLHF_VECTOR_FORCE_PRIMARY_FAILURE;
+    delete process.env.RLHF_VECTOR_STUB_EMBED;
+    fs.rmSync(tmpFeedbackDir, { recursive: true, force: true });
+  }
+
+  const passed = report.summary.failed === 0 && report.testResults.failed === 0;
+  const jsonPath = path.join(proofDir, 'local-intelligence-report.json');
+  const mdPath = path.join(proofDir, 'local-intelligence-report.md');
+
+  fs.writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`);
+
+  const lines = [
+    '# Local Intelligence Proof Report',
+    '',
+    `Status: ${passed ? 'PASSED' : 'FAILED'}`,
+    `Generated: ${report.generatedAt}`,
+    '',
+    '## Test Results',
+    '',
+    `- Passed: ${report.testResults.passed}`,
+    `- Failed: ${report.testResults.failed}`,
+    '',
+    '## Checks',
+    '',
+  ];
+
+  report.checks.forEach((check) => {
+    lines.push(`- ${check.id}: ${check.passed ? 'PASS' : 'FAIL'} — ${check.evidence}`);
+  });
+
+  fs.writeFileSync(mdPath, `${lines.join('\n')}\n`);
+
+  process.stdout.write(`Status: ${passed ? 'PASSED' : 'FAILED'}\n`);
+  process.stdout.write(`JSON report: ${jsonPath}\n`);
+  process.stdout.write(`Markdown report: ${mdPath}\n`);
+  process.exit(passed ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error(`prove-local-intelligence failed: ${err.message}`);
+  process.exit(1);
+});

package/scripts/prove-loop-closure.js

@@ -18,13 +18,21 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const PROOF_DIR = path.join(__dirname, '..', 'proof');
-const REPORT_JSON = path.join(PROOF_DIR, 'loop-closure-report.json');
-const REPORT_MD = path.join(PROOF_DIR, 'loop-closure-report.md');
+const ROOT = path.join(__dirname, '..');
+
+function resolveProofPaths() {
+  const proofDir = process.env.RLHF_PROOF_DIR || path.join(ROOT, 'proof');
+  return {
+    proofDir,
+    reportJson: path.join(proofDir, 'loop-closure-report.json'),
+    reportMd: path.join(proofDir, 'loop-closure-report.md'),
+  };
+}
 
 function run() {
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rlhf-loop-proof-'));
   const results = { passed: 0, failed: 0, requirements: {} };
+  const { proofDir, reportJson, reportMd } = resolveProofPaths();
 
   const checks = [
     {
@@ -168,7 +176,7 @@ function run() {
       desc: 'test:loop-closure (node --test tests/loop-closure.test.js) passes with 0 failures',
       fn: () => {
         const out = execSync('node --test tests/loop-closure.test.js', {
-          cwd: path.join(__dirname, '..'),
+          cwd: ROOT,
           env: { ...process.env, RLHF_FEEDBACK_DIR: tmpDir },
           encoding: 'utf8',
           stdio: 'pipe',
@@ -207,7 +215,7 @@ function run() {
   } catch {}
 
   // Write proof artifacts
-  fs.mkdirSync(PROOF_DIR, { recursive: true });
+  fs.mkdirSync(proofDir, { recursive: true });
 
   const report = {
     phase: '08-loop-closure',
@@ -218,7 +226,7 @@ function run() {
     requirements: results.requirements,
   };
 
-  fs.writeFileSync(REPORT_JSON, JSON.stringify(report, null, 2) + '\n');
+  fs.writeFileSync(reportJson, JSON.stringify(report, null, 2) + '\n');
 
   const md = [
     '# Phase 8: Loop Closure — Proof Report',
@@ -244,10 +252,10 @@ function run() {
     '',
   ].join('\n');
 
-  fs.writeFileSync(REPORT_MD, md);
+  fs.writeFileSync(reportMd, md);
 
   console.log(`\nPhase 8 proof: ${results.passed} passed, ${results.failed} failed`);
-  console.log(`Report: ${REPORT_JSON}`);
+  console.log(`Report: ${reportJson}`);
 
   if (results.failed > 0) process.exit(1);
 }

package/scripts/prove-training-export.js

@@ -15,7 +15,9 @@ const path = require('path');
 const { execSync } = require('child_process');
 
 const ROOT = path.join(__dirname, '..');
-const PROOF_DIR = path.join(ROOT, 'proof');
+function getProofDir() {
+  return process.env.RLHF_PROOF_DIR || path.join(ROOT, 'proof');
+}
 
 function ensureDir(d) {
   if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
@@ -251,9 +253,10 @@ async function main() {
     overallPassed: allPassed,
   };
 
-  ensureDir(PROOF_DIR);
-  const jsonPath = path.join(PROOF_DIR, 'training-export-report.json');
-  const mdPath = path.join(PROOF_DIR, 'training-export-report.md');
+  const proofDir = getProofDir();
+  ensureDir(proofDir);
+  const jsonPath = path.join(proofDir, 'training-export-report.json');
+  const mdPath = path.join(proofDir, 'training-export-report.md');
 
   fs.writeFileSync(jsonPath, JSON.stringify(report, null, 2));
 

package/scripts/prove-workflow-contract.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  runWorkflowContractValidation,
+} = require('./validate-workflow-contract');
+
+const PROJECT_ROOT = path.join(__dirname, '..');
+const DEFAULT_PROOF_DIR = path.join(PROJECT_ROOT, 'proof', 'workflow-contract');
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function toMarkdown(report) {
+  const lines = [
+    '# Workflow Contract Proof Report',
+    '',
+    `Generated: ${report.generatedAt}`,
+    '',
+    `Summary: ${report.summary.passed} passed, ${report.summary.failed} failed`,
+    '',
+    '## Validated Files',
+    '',
+    ...Object.values(report.files).map((filePath) => `- \`${filePath}\``),
+    '',
+    '## Checks',
+    '',
+  ];
+
+  report.checks.forEach((check) => {
+    lines.push(`- ${check.name}: ${check.passed ? 'PASS' : 'FAIL'}`);
+  });
+
+  if (report.issues.length > 0) {
+    lines.push('');
+    lines.push('## Issues');
+    lines.push('');
+    report.issues.forEach((issue) => {
+      lines.push(`- ${issue}`);
+    });
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function runWorkflowContractProof(options = {}) {
+  const proofDir = options.proofDir || process.env.RLHF_WORKFLOW_CONTRACT_PROOF_DIR || DEFAULT_PROOF_DIR;
+  const writeArtifacts = options.writeArtifacts !== false;
+  const validation = runWorkflowContractValidation({ projectRoot: options.projectRoot || PROJECT_ROOT });
+
+  const report = {
+    generatedAt: validation.generatedAt,
+    files: validation.files,
+    checks: [
+      {
+        name: 'workflow.contract.complete',
+        passed: validation.ok,
+        details: {
+          headingsFound: validation.details.workflow ? validation.details.workflow.headingsFound : [],
+          proofCommandsFound: validation.details.workflow ? validation.details.workflow.proofCommandsFound : [],
+        },
+      },
+      {
+        name: 'issue.template.complete',
+        passed: validation.ok,
+        details: {
+          fieldIdsFound: validation.details.issueTemplate ? validation.details.issueTemplate.fieldIdsFound : [],
+        },
+      },
+      {
+        name: 'pull_request.template.complete',
+        passed: validation.ok,
+        details: {
+          sectionsFound: validation.details.pullRequestTemplate ? validation.details.pullRequestTemplate.sectionsFound : [],
+        },
+      },
+      {
+        name: 'readme.links.contracts',
+        passed: validation.ok,
+        details: validation.details.readme || {},
+      },
+    ],
+    issues: validation.issues.slice(),
+    summary: {
+      passed: validation.ok ? 4 : 0,
+      failed: validation.ok ? 0 : 4,
+    },
+  };
+
+  if (writeArtifacts) {
+    ensureDir(proofDir);
+    fs.writeFileSync(path.join(proofDir, 'report.json'), JSON.stringify(report, null, 2));
+    fs.writeFileSync(path.join(proofDir, 'report.md'), toMarkdown(report));
+  }
+
+  return report;
+}
+
+if (require.main === module) {
+  const report = runWorkflowContractProof();
+  if (report.summary.failed > 0) {
+    console.error(toMarkdown(report));
+    process.exit(1);
+  }
+
+  console.log(toMarkdown(report));
+}
+
+module.exports = {
+  DEFAULT_PROOF_DIR,
+  runWorkflowContractProof,
+  toMarkdown,
+};

package/scripts/reminder-engine.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_ROOT = path.join(__dirname, '..');
+const DEFAULT_STATE_PATH = path.join(PROJECT_ROOT, '.rlhf', 'reminder-state.json');
+
+const REMINDER_TEMPLATES = {
+  guardrail_spike: 'Safety guardrails triggered {{count}} times. Re-apply rule: {{rule}}',
+  iteration_limit: 'Approaching max iterations ({{count}}/{{limit}}). Prioritize essential actions only.',
+  tool_misuse: 'Tool misuse detected {{count}} times for: {{tools}}. Verify tool schemas before calling.',
+  error_cascade: 'Repeated errors ({{count}}). Switch strategy: {{suggestion}}',
+};
+
+const DEFAULT_THRESHOLDS = {
+  guardrail_spike: 3,
+  iteration_limit: 1,
+  tool_misuse: 2,
+  error_cascade: 3,
+};
+
+function getStatePath(stateFile) {
+  return stateFile || DEFAULT_STATE_PATH;
+}
+
+function loadState(stateFile) {
+  const p = getStatePath(stateFile);
+  try {
+    if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    // corrupted — start fresh
+  }
+  return { counts: {} };
+}
+
+function saveState(state, stateFile) {
+  const p = getStatePath(stateFile);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(state, null, 2));
+}
+
+/**
+ * Increment the event counter for a given event type.
+ * @param {string} eventType - One of the keys in REMINDER_TEMPLATES
+ * @param {string} [stateFile] - Path to state JSON (default: .rlhf/reminder-state.json)
+ * @returns {number} New count after incrementing
+ */
+function trackEvent(eventType, stateFile) {
+  const state = loadState(stateFile);
+  state.counts[eventType] = (state.counts[eventType] || 0) + 1;
+  saveState(state, stateFile);
+  return state.counts[eventType];
+}
+
+/**
+ * Get the current event count without modifying state.
+ * @param {string} eventType
+ * @param {string} [stateFile]
+ * @returns {number}
+ */
+function getEventCount(eventType, stateFile) {
+  return loadState(stateFile).counts[eventType] || 0;
+}
+
+/**
+ * Return true if the event count meets or exceeds its threshold.
+ * @param {string} eventType
+ * @param {number} [threshold] - Defaults to DEFAULT_THRESHOLDS[eventType] or 3
+ * @param {string} [stateFile]
+ * @returns {boolean}
+ */
+function shouldInjectReminder(eventType, threshold, stateFile) {
+  const t = typeof threshold === 'number' ? threshold : (DEFAULT_THRESHOLDS[eventType] || 3);
+  return getEventCount(eventType, stateFile) >= t;
+}
+
+/**
+ * Render a reminder template with context variable substitution.
+ * @param {string} eventType
+ * @param {object} ctx - Variables to substitute into {{var}} placeholders
+ * @returns {string}
+ */
+function renderTemplate(eventType, ctx) {
+  const template = REMINDER_TEMPLATES[eventType];
+  if (!template) return `[Reminder] Event: ${eventType}`;
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => (ctx && ctx[key] !== undefined ? ctx[key] : `{${key}}`));
+}
+
+/**
+ * Append a system reminder to a turns array without modifying state.
+ * Callers are responsible for calling trackEvent before/after as needed.
+ * @param {object[]} turns - Existing turns array
+ * @param {string} eventType
+ * @param {object} ctx - Template variables (count will be added automatically)
+ * @param {string} [stateFile]
+ * @returns {object[]} New turns array with reminder appended
+ */
+function injectReminder(turns, eventType, ctx, stateFile) {
+  const count = getEventCount(eventType, stateFile);
+  const message = renderTemplate(eventType, { ...ctx, count });
+  const reminder = {
+    role: 'user',
+    content: `[System Reminder] ${message}`,
+    injectedAt: new Date().toISOString(),
+    eventType,
+  };
+  return [...turns, reminder];
+}
+
+/**
+ * Reset the event counter for a given event type (e.g., after a reminder is acted on).
+ * @param {string} eventType
+ * @param {string} [stateFile]
+ */
+function resetEvent(eventType, stateFile) {
+  const state = loadState(stateFile);
+  state.counts[eventType] = 0;
+  saveState(state, stateFile);
+}
+
+module.exports = {
+  REMINDER_TEMPLATES,
+  DEFAULT_THRESHOLDS,
+  DEFAULT_STATE_PATH,
+  trackEvent,
+  getEventCount,
+  shouldInjectReminder,
+  renderTemplate,
+  injectReminder,
+  resetEvent,
+};