fraim 2.0.270 → 2.0.272

package/dist/src/local-mcp-server/learning-usage-store.js

@@ -0,0 +1,417 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOCK_ADVANCING_OUTCOMES = exports.FIRING_OUTCOMES = void 0;
+exports.resolveUsageStorePath = resolveUsageStorePath;
+exports.resolveUsageLimits = resolveUsageLimits;
+exports.normalizeEntryTitle = normalizeEntryTitle;
+exports.titleUsageKey = titleUsageKey;
+exports.ruleUsageKey = ruleUsageKey;
+exports.readUsageStore = readUsageStore;
+exports.sanitizeNote = sanitizeNote;
+exports.recordOffers = recordOffers;
+exports.recordFirings = recordFirings;
+exports.noteTitleChange = noteTitleChange;
+exports.pruneUsageStore = pruneUsageStore;
+/**
+ * Issue #1103 — the usage record for learnings and rules.
+ *
+ * Two sides of one boundary, because only one of them is observable:
+ *
+ *   OFFERED — written by the runtime with no agent involvement. The proxy composes
+ *             the injected context block, so it knows which files it listed and,
+ *             for the score-gated families, which entries in them were above
+ *             threshold. That is what an offer means here.
+ *   FIRED   — attested by the agent at retrospective time. FRAIM cannot observe a
+ *             file read, and a read is not a use, so influence has to be claimed
+ *             rather than inferred.
+ *
+ * The record is metadata only (R16): entry identity, outcome, date, job, agent,
+ * model. Never prompts, diffs, or work content. Notes are reduced to one bounded
+ * line so a multi-line diff cannot be smuggled in through the attestation.
+ *
+ * Aggregate counters are kept in full; the detailed logs are bounded (R16a), on
+ * Mem0's precedent of retaining the last 20 accesses rather than an unbounded
+ * behavioural history.
+ *
+ * The store lives inside the manager layer's content root, which is the layer the
+ * existing GDPR guardrail blocks from a git backend without an explicit override
+ * (`src/ai-hub/server.ts`). That placement is what satisfies R18; there is no
+ * second guardrail here.
+ *
+ * It is derived data (R17): deleting it loses no lesson, because every firing is
+ * still written in the retrospective that attested it and every offer is
+ * re-recorded the next time the entry is delivered.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const pack_home_1 = require("../cli/utils/pack-home");
+const artifact_retention_cleanup_1 = require("./artifact-retention-cleanup");
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+// ── Vocabulary ───────────────────────────────────────────────────────────────
+/**
+ * The five outcomes (spec: Outcome vocabulary). `ignored` and `not-offered` are
+ * the two that change what the manager should do: the first says fix the entry,
+ * the second says fix the delivery.
+ */
+exports.FIRING_OUTCOMES = ['prevented', 'applied', 'not-applicable', 'ignored', 'not-offered'];
+/**
+ * R8: only these advance the decay clock. An entry that was offered, read, and
+ * correctly not relevant has not proved anything about its usefulness.
+ */
+exports.CLOCK_ADVANCING_OUTCOMES = ['prevented', 'applied'];
+const STORE_VERSION = 1;
+const STORE_FILE_NAME = 'learning-usage.json';
+/** Default bounds. The firing bound follows Mem0's published 20-access retention. */
+const DEFAULT_FIRING_LOG_LIMIT = 20;
+/**
+ * The offer log is larger than the firing log because R7 has to answer "was this
+ * entry in context for that job" across a plausible recurrence window, which
+ * needs per-job offer detail rather than a counter.
+ */
+const DEFAULT_OFFER_LOG_LIMIT = 50;
+/** Open Question 2: configurable and greater than a handful. */
+const DEFAULT_RETIREMENT_OFFER_THRESHOLD = 10;
+/** R16: one line, bounded, no fences. Long enough for a sentence, short enough to be useless as a transcript. */
+const MAX_NOTE_LENGTH = 240;
+// ── Paths and config ─────────────────────────────────────────────────────────
+/**
+ * The store path, inside the manager layer so the existing git-backend guardrail
+ * covers it. `resolvePackHome` never touches the network and never throws.
+ */
+function resolveUsageStorePath() {
+    return (0, path_1.join)((0, pack_home_1.resolvePackHome)('manager').contentRoot, 'usage', STORE_FILE_NAME);
+}
+function readWorkspaceConfig(workspaceRoot) {
+    try {
+        const configPath = (0, project_fraim_paths_1.getWorkspaceConfigPath)(workspaceRoot);
+        if (!(0, fs_1.existsSync)(configPath))
+            return {};
+        return JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function positiveInt(value, fallback) {
+    return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function resolveUsageLimits(workspaceRoot) {
+    const usage = readWorkspaceConfig(workspaceRoot)?.learning?.usage;
+    const block = usage && typeof usage === 'object' && !Array.isArray(usage) ? usage : {};
+    let retentionDays = -1;
+    try {
+        retentionDays = (0, artifact_retention_cleanup_1.resolveArtifactRetentionConfig)(workspaceRoot).values.learning_usage;
+    }
+    catch {
+        // Retention config is advisory here; a malformed config must not stop a write.
+    }
+    return {
+        firingLogLimit: positiveInt(block.firingLogLimit, DEFAULT_FIRING_LOG_LIMIT),
+        offerLogLimit: positiveInt(block.offerLogLimit, DEFAULT_OFFER_LOG_LIMIT),
+        retirementOfferThreshold: positiveInt(block.retirementOfferThreshold, DEFAULT_RETIREMENT_OFFER_THRESHOLD),
+        retentionDays: typeof retentionDays === 'number' ? retentionDays : -1,
+    };
+}
+// ── Keys ─────────────────────────────────────────────────────────────────────
+/** Normalize a title for keying. Case and whitespace only: never a similarity measure (D4). */
+function normalizeEntryTitle(title) {
+    return title.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+/**
+ * The fallback key for an entry that carries no `**Id**` line yet, so the feature
+ * works before the id migration has run. Namespaced by family so the same title
+ * in two families is two entries.
+ */
+function titleUsageKey(fileType, title) {
+    return `T:${fileType}:${normalizeEntryTitle(title)}`;
+}
+/** The key for a rule file, namespaced so it can never collide with a learning id. */
+function ruleUsageKey(displayPath) {
+    return `R:${displayPath.replace(/\\/g, '/')}`;
+}
+// ── Read and write ───────────────────────────────────────────────────────────
+function emptyStore() {
+    return { version: STORE_VERSION, updatedAt: new Date(0).toISOString(), entries: {} };
+}
+/**
+ * Is this parsed value a record every consumer can read without crashing?
+ *
+ * The shallow `record.offered && record.fired` this replaced was not enough. A
+ * record whose sub-objects exist but are empty passed it and then threw in
+ * `buildUsageReport` (`record.offered.log is not iterable`),
+ * `findRetirementCandidates` and `deriveStanding`, so usage reports and
+ * candidate analysis failed outright instead of degrading. That state is
+ * reachable: the store is a JSON file inside the manager home, which is commonly
+ * a synced folder, so an interrupted write or a partial sync produces valid JSON
+ * with a hollow record.
+ *
+ * Checks only what a consumer actually dereferences, so a record carrying an
+ * unknown extra field is still accepted and a future field addition does not
+ * silently start discarding history.
+ */
+function isUsableRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    const offered = record.offered;
+    const fired = record.fired;
+    if (!offered || typeof offered !== 'object' || !fired || typeof fired !== 'object')
+        return false;
+    return Array.isArray(offered.log)
+        && typeof offered.total === 'number'
+        && typeof offered.aboveThreshold === 'number'
+        && !!offered.byModel && typeof offered.byModel === 'object'
+        && Array.isArray(fired.log)
+        && typeof fired.total === 'number'
+        && !!fired.byOutcome && typeof fired.byOutcome === 'object'
+        && Array.isArray(record.titles);
+}
+/**
+ * A missing or corrupt store reads as empty. It is derived data, so losing it is
+ * recoverable and must never break the loader that reads it.
+ */
+function readUsageStore(storePath = resolveUsageStorePath()) {
+    try {
+        if (!(0, fs_1.existsSync)(storePath))
+            return emptyStore();
+        const parsed = JSON.parse((0, fs_1.readFileSync)(storePath, 'utf8'));
+        // `typeof [] === 'object'`, so an array has to be rejected explicitly: otherwise
+        // Object.values yields whatever the array held and every consumer that reads
+        // `entry.offered` throws on it.
+        if (!parsed || typeof parsed !== 'object' || !parsed.entries
+            || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
+            return emptyStore();
+        }
+        // Drop any value that is not a usable record rather than handing a caller
+        // something it will crash on. A partially corrupt store degrades to the records
+        // that are still readable, which is the right behaviour for derived data.
+        const entries = {};
+        for (const [key, value] of Object.entries(parsed.entries)) {
+            if (isUsableRecord(value))
+                entries[key] = value;
+        }
+        return { version: parsed.version ?? STORE_VERSION, updatedAt: parsed.updatedAt ?? emptyStore().updatedAt, entries };
+    }
+    catch {
+        return emptyStore();
+    }
+}
+function writeUsageStore(store, storePath = resolveUsageStorePath()) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(storePath), { recursive: true });
+    (0, fs_1.writeFileSync)(storePath, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+}
+// ── Mutation helpers ─────────────────────────────────────────────────────────
+function emptyOutcomeCounts() {
+    return { prevented: 0, applied: 0, 'not-applicable': 0, ignored: 0, 'not-offered': 0 };
+}
+function ensureRecord(store, key, family, fileType, level) {
+    const existing = store.entries[key];
+    if (existing) {
+        if (fileType && !existing.fileType)
+            existing.fileType = fileType;
+        if (level && !existing.level)
+            existing.level = level;
+        return existing;
+    }
+    const created = {
+        key,
+        family,
+        titles: [],
+        fileType: fileType ?? null,
+        level: level ?? null,
+        offered: { total: 0, aboveThreshold: 0, byModel: {}, lastOfferedAt: null, log: [] },
+        fired: {
+            total: 0, byOutcome: emptyOutcomeCounts(), byModel: {},
+            firstFiredAt: null, lastFiredAt: null, lastAttestedAt: null, log: [], seenSources: [],
+        },
+    };
+    store.entries[key] = created;
+    return created;
+}
+function rememberTitle(record, title) {
+    if (!title)
+        return;
+    const trimmed = title.trim();
+    if (!trimmed)
+        return;
+    const normalized = normalizeEntryTitle(trimmed);
+    const already = record.titles.findIndex((t) => normalizeEntryTitle(t) === normalized);
+    // Already the most recent title: nothing to do. Guard the empty case explicitly,
+    // because findIndex returns -1 and length - 1 is also -1 on an empty list.
+    if (record.titles.length > 0 && already === record.titles.length - 1)
+        return;
+    if (already >= 0)
+        record.titles.splice(already, 1);
+    record.titles.push(trimmed);
+}
+/**
+ * R16: reduce an attested note to a single bounded line. This is the control that
+ * keeps a diff, a prompt, or a transcript out of a behavioural record.
+ */
+function sanitizeNote(note) {
+    const oneLine = String(note ?? '')
+        .replace(/```+/g, ' ')
+        .replace(/[\r\n\t]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return oneLine.length > MAX_NOTE_LENGTH ? `${oneLine.slice(0, MAX_NOTE_LENGTH - 1).trimEnd()}…` : oneLine;
+}
+function maxDate(a, b) {
+    if (!a)
+        return b;
+    return b > a ? b : a;
+}
+function minDate(a, b) {
+    if (!a)
+        return b;
+    return b < a ? b : a;
+}
+function isValidDate(value) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(new Date(value).getTime());
+}
+function withinRetention(date, retentionDays, now) {
+    if (retentionDays < 0)
+        return true;
+    const parsed = new Date(date).getTime();
+    if (Number.isNaN(parsed))
+        return true;
+    return (now.getTime() - parsed) / 86_400_000 <= retentionDays;
+}
+/**
+ * Trim one entry's logs: drop records outside the retention window, then keep the
+ * newest N. Aggregates are never touched, so R16a's second criterion holds.
+ */
+function trimLogs(record, limits, now) {
+    const byDate = (a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0);
+    record.offered.log = record.offered.log
+        .filter((r) => withinRetention(r.date, limits.retentionDays, now))
+        .sort(byDate)
+        .slice(-limits.offerLogLimit);
+    record.fired.log = record.fired.log
+        .filter((r) => withinRetention(r.date, limits.retentionDays, now))
+        .sort(byDate)
+        .slice(-limits.firingLogLimit);
+}
+/**
+ * R1 and R2: write one offer record per listed entry, without any agent
+ * involvement and without depending on the agent reading the file.
+ */
+function recordOffers(offers, options) {
+    const storePath = options.storePath ?? resolveUsageStorePath();
+    const now = options.now ?? new Date();
+    const store = readUsageStore(storePath);
+    let recorded = 0;
+    for (const offer of offers) {
+        if (!offer.key || !isValidDate(offer.date))
+            continue;
+        const record = ensureRecord(store, offer.key, offer.family, offer.fileType, offer.level);
+        rememberTitle(record, offer.title);
+        record.offered.total += 1;
+        if (offer.aboveThreshold)
+            record.offered.aboveThreshold += 1;
+        if (offer.model)
+            record.offered.byModel[offer.model] = (record.offered.byModel[offer.model] ?? 0) + 1;
+        record.offered.lastOfferedAt = maxDate(record.offered.lastOfferedAt, offer.date);
+        record.offered.log.push({
+            date: offer.date,
+            job: offer.job,
+            agent: offer.agent ?? null,
+            model: offer.model ?? null,
+            aboveThreshold: Boolean(offer.aboveThreshold),
+        });
+        trimLogs(record, options.limits, now);
+        recorded += 1;
+    }
+    if (recorded > 0) {
+        store.updatedAt = now.toISOString();
+        writeUsageStore(store, storePath);
+    }
+    return { recorded, entries: Object.keys(store.entries).length };
+}
+/**
+ * R4 and R6: write the attested firings. Idempotent per (entry, attestation
+ * source) so a re-run, or a backfill that overlaps a live attestation, cannot
+ * inflate a count.
+ */
+function recordFirings(firings, options) {
+    const storePath = options.storePath ?? resolveUsageStorePath();
+    const now = options.now ?? new Date();
+    const store = readUsageStore(storePath);
+    let recorded = 0;
+    let alreadyRecorded = 0;
+    for (const firing of firings) {
+        if (!exports.FIRING_OUTCOMES.includes(firing.outcome)) {
+            throw new Error(`Unknown firing outcome "${firing.outcome}". Use one of: ${exports.FIRING_OUTCOMES.join(', ')}.`);
+        }
+        if (!firing.key || !isValidDate(firing.date))
+            continue;
+        const record = ensureRecord(store, firing.key, firing.family, firing.fileType, firing.level);
+        if (firing.sourceRef && record.fired.seenSources.includes(firing.sourceRef)) {
+            alreadyRecorded += 1;
+            continue;
+        }
+        rememberTitle(record, firing.title);
+        record.fired.total += 1;
+        record.fired.byOutcome[firing.outcome] += 1;
+        record.fired.lastAttestedAt = maxDate(record.fired.lastAttestedAt, firing.date);
+        if (exports.CLOCK_ADVANCING_OUTCOMES.includes(firing.outcome)) {
+            record.fired.firstFiredAt = minDate(record.fired.firstFiredAt, firing.date);
+            record.fired.lastFiredAt = maxDate(record.fired.lastFiredAt, firing.date);
+            if (firing.model)
+                record.fired.byModel[firing.model] = (record.fired.byModel[firing.model] ?? 0) + 1;
+        }
+        record.fired.log.push({
+            date: firing.date,
+            outcome: firing.outcome,
+            job: firing.job,
+            agent: firing.agent ?? null,
+            model: firing.model ?? null,
+            note: sanitizeNote(firing.note),
+            source: firing.source ?? 'attested',
+        });
+        if (firing.sourceRef)
+            record.fired.seenSources.push(firing.sourceRef);
+        trimLogs(record, options.limits, now);
+        recorded += 1;
+    }
+    if (recorded > 0 || alreadyRecorded > 0) {
+        store.updatedAt = now.toISOString();
+        writeUsageStore(store, storePath);
+    }
+    return { recorded, alreadyRecorded };
+}
+/**
+ * R5: record that an entry's title changed, so a firing written before the edit
+ * still resolves to it. Identity lives on the entry; this keeps the store's title
+ * index able to follow a rename.
+ */
+function noteTitleChange(key, newTitle, options) {
+    const storePath = options.storePath ?? resolveUsageStorePath();
+    const store = readUsageStore(storePath);
+    const record = store.entries[key];
+    if (!record)
+        return;
+    rememberTitle(record, newTitle);
+    store.updatedAt = (options.now ?? new Date()).toISOString();
+    writeUsageStore(store, storePath);
+}
+/** Apply retention and log bounds across the whole store. Reports what it dropped. */
+function pruneUsageStore(limits, options = {}) {
+    const storePath = options.storePath ?? resolveUsageStorePath();
+    const now = options.now ?? new Date();
+    const store = readUsageStore(storePath);
+    let prunedOfferRecords = 0;
+    let prunedFiringRecords = 0;
+    for (const record of Object.values(store.entries)) {
+        const offersBefore = record.offered.log.length;
+        const firingsBefore = record.fired.log.length;
+        trimLogs(record, limits, now);
+        prunedOfferRecords += offersBefore - record.offered.log.length;
+        prunedFiringRecords += firingsBefore - record.fired.log.length;
+    }
+    if (prunedOfferRecords > 0 || prunedFiringRecords > 0) {
+        store.updatedAt = now.toISOString();
+        writeUsageStore(store, storePath);
+    }
+    return { prunedOfferRecords, prunedFiringRecords, entries: Object.keys(store.entries).length };
+}

package/dist/src/local-mcp-server/stdio-server.js

@@ -70,6 +70,7 @@ const usage_collector_js_1 = require("./usage-collector.js");
 const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
 const token_adapter_registry_js_1 = require("./token-adapter-registry.js");
 const learning_context_builder_js_1 = require("./learning-context-builder.js");
+const learning_usage_store_js_1 = require("./learning-usage-store.js");
 const learning_domains_js_1 = require("../config/learning-domains.js");
 const skill_include_dedup_js_1 = require("./skill-include-dedup.js");
 /**
@@ -1371,6 +1372,7 @@ class FraimLocalMCPServer {
                         responseText += teamContextSection;
                         this.log(`[req:${requestId}] Injected team context from ${workspaceRoot}`);
                     }
+                    this.recordUsageOffers(workspaceRoot, userEmail, false, null, 'session', requestId);
                 }
                 if (this.latestConnectSyncWarning) {
                     responseText += `\n\n## Local Catalog\n${this.latestConnectSyncWarning}`;
@@ -1391,10 +1393,51 @@ class FraimLocalMCPServer {
                     finalizedResponse.result.content[0].text = text + `\n\n---` + learningSection + teamContextSection;
                     this.log(`[req:${requestId}] Injected job-focus learning/team context for ${userEmail} (domain: ${jobDomain ?? 'global'})`);
                 }
+                this.recordUsageOffers(workspaceRoot, userEmail, true, jobDomain, String(args.job ?? 'unknown'), requestId);
             }
         }
         return this.processResponseWithHydration(finalizedResponse, requestSessionId);
     }
+    /**
+     * Issue #1103 R1, R2 and R3: record what this context injection delivered.
+     *
+     * Written here because this is the only place that knows all of it at once: the
+     * files that were listed, the job, the agent, and the model. Nothing depends on
+     * the agent reading anything, which is R2, and the three auto-loaded rule files
+     * get a record for the first time, which is R3.
+     *
+     * Never throws and never blocks the response. Usage data is derived and optional:
+     * a failure here must not change what the agent is given.
+     */
+    recordUsageOffers(workspaceRoot, userEmail, forJob, domain, job, requestId) {
+        try {
+            const offered = [
+                ...(0, learning_context_builder_js_1.collectOfferedLearningEntries)(workspaceRoot, userEmail, forJob, domain),
+                ...(0, learning_context_builder_js_1.collectOfferedRuleFiles)(workspaceRoot, forJob),
+            ];
+            if (offered.length === 0)
+                return;
+            const collector = this.usageCollector;
+            const date = new Date().toISOString().slice(0, 10);
+            const limits = (0, learning_usage_store_js_1.resolveUsageLimits)(workspaceRoot);
+            const result = (0, learning_usage_store_js_1.recordOffers)(offered.map((entry) => ({
+                key: entry.key,
+                family: entry.family,
+                title: entry.title,
+                fileType: entry.fileType,
+                level: entry.level,
+                aboveThreshold: entry.aboveThreshold,
+                job,
+                date,
+                agent: collector?.getAgentName() ?? null,
+                model: collector?.getAgentModel() ?? null,
+            })), { limits });
+            this.log(`[req:${requestId}] Recorded ${result.recorded} usage offers for job ${job}`);
+        }
+        catch (error) {
+            this.log(`[req:${requestId}] Usage offer recording skipped: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     /**
      * Resolve the learning domain for a `get_fraim_job` request (issue #806) from
      * the job's registry path, so the loader injects global + that domain's

package/dist/src/services/provider-service.js

@@ -12,7 +12,7 @@ const PROVIDERS = {
         description: 'GitHub repository and issue management',
         capabilities: ['code', 'issues', 'integrated'],
         docsUrl: 'https://github.com/settings/tokens',
-        setupInstructions: 'Run "fraim add-provider github" — your IDE handles OAuth automatically on first use',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current GitHub and host guidance',
         mcpServer: {
             type: 'http',
             url: 'https://api.githubcopilot.com/mcp/'
@@ -25,7 +25,7 @@ const PROVIDERS = {
         description: 'GitLab repository and issue management',
         capabilities: ['code', 'issues', 'integrated'],
         docsUrl: 'https://gitlab.com/-/profile/personal_access_tokens',
-        setupInstructions: 'Create a Personal Access Token at https://gitlab.com/-/profile/personal_access_tokens with api scope',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current GitLab and host guidance',
         mcpServer: {
             type: 'http',
             url: 'https://gitlab.com/api/v4/mcp',
@@ -49,7 +49,7 @@ const PROVIDERS = {
             }
         ],
         docsUrl: 'https://dev.azure.com',
-        setupInstructions: 'Create a Personal Access Token in Azure DevOps with Code (Read & Write) and Work Items (Read & Write) scopes',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current Azure DevOps and host guidance',
         mcpServer: {
             type: 'stdio',
             command: 'npx',
@@ -91,7 +91,7 @@ const PROVIDERS = {
             }
         ],
         docsUrl: 'https://id.atlassian.com/manage-profile/security/api-tokens',
-        setupInstructions: 'Create an API Token at https://id.atlassian.com/manage-profile/security/api-tokens',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current Jira and host guidance',
         mcpServer: {
             type: 'stdio',
             command: 'uvx',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.270",
+  "version": "2.0.272",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {