fraim-framework 2.0.124 → 2.0.127

package/dist/src/local-mcp-server/agent-token-prices.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Static price table for converting per-agent token counters to USD.
+ *
+ * Issue #330 / R1.3 / C4 (ISO 27001 A.5.31).
+ *
+ * Each entry MUST carry `source` (a citation pointing back to the vendor's
+ * published pricing page) and `verifiedOn` (an ISO date string). The
+ * `agent-token-prices.test.ts` lint fails CI if any entry exceeds 180 days
+ * since `verifiedOn` so this table is reviewed at least quarterly.
+ *
+ * Prices are USD per million tokens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_TOKEN_PRICES = void 0;
+exports.lookupPrice = lookupPrice;
+exports.computeCostUsd = computeCostUsd;
+exports.AGENT_TOKEN_PRICES = [
+    // Anthropic — Claude (used by Claude Code).
+    // Note: when Claude Code emits cost via OTLP we read it directly; this
+    // table backstops cost computation for legacy/no-cost-metric snapshots
+    // and lets per-agent comparison panels report a model-attributed cost
+    // even when a snapshot lacks a costUsd field.
+    {
+        agent: 'claude-code',
+        model: 'claude-opus-4-7',
+        inputPerMTok: 15.00,
+        outputPerMTok: 75.00,
+        cacheReadPerMTok: 1.50,
+        cacheCreationPerMTok: 18.75,
+        source: 'https://www.anthropic.com/pricing',
+        verifiedOn: '2026-04-29',
+    },
+    {
+        agent: 'claude-code',
+        model: 'claude-sonnet-4-6',
+        inputPerMTok: 3.00,
+        outputPerMTok: 15.00,
+        cacheReadPerMTok: 0.30,
+        cacheCreationPerMTok: 3.75,
+        source: 'https://www.anthropic.com/pricing',
+        verifiedOn: '2026-04-29',
+    },
+    {
+        agent: 'claude-code',
+        model: 'claude-haiku-4-5',
+        inputPerMTok: 1.00,
+        outputPerMTok: 5.00,
+        cacheReadPerMTok: 0.10,
+        cacheCreationPerMTok: 1.25,
+        source: 'https://www.anthropic.com/pricing',
+        verifiedOn: '2026-04-29',
+    },
+    // OpenAI — GPT-5 Codex (used by Codex CLI).
+    {
+        agent: 'codex',
+        model: 'gpt-5-codex',
+        inputPerMTok: 5.00,
+        outputPerMTok: 15.00,
+        cacheReadPerMTok: 0.50,
+        cacheCreationPerMTok: 0,
+        source: 'https://openai.com/api/pricing/',
+        verifiedOn: '2026-04-29',
+    },
+    {
+        agent: 'codex',
+        model: 'gpt-5',
+        inputPerMTok: 5.00,
+        outputPerMTok: 15.00,
+        cacheReadPerMTok: 0.50,
+        cacheCreationPerMTok: 0,
+        source: 'https://openai.com/api/pricing/',
+        verifiedOn: '2026-04-29',
+    },
+    // Real Codex CLI 0.125.0 emits `gpt-5.5` on turn_context.payload.model.
+    // Treated as the gpt-5 family for pricing until OpenAI publishes a
+    // distinct rate card. Conservative estimate; refresh on next quarterly
+    // verification pass.
+    {
+        agent: 'codex',
+        model: 'gpt-5.5',
+        inputPerMTok: 5.00,
+        outputPerMTok: 15.00,
+        cacheReadPerMTok: 0.50,
+        cacheCreationPerMTok: 0,
+        source: 'https://openai.com/api/pricing/ (gpt-5 row, applied to gpt-5.5 as nearest published rate)',
+        verifiedOn: '2026-04-30',
+    },
+];
+/**
+ * Look up the price entry for an agent + model. Agent is matched
+ * case-insensitively. Returns null when no matching entry exists — the
+ * adapter is then expected to skip cost computation rather than guess.
+ */
+function lookupPrice(agent, model) {
+    if (!agent || !model)
+        return null;
+    const a = agent.toLowerCase();
+    return exports.AGENT_TOKEN_PRICES.find(e => e.agent === a && e.model === model) || null;
+}
+/**
+ * Compute USD cost from cumulative token counts. Returns 0 when no price
+ * entry exists for the agent/model — the caller decides whether to drop
+ * the snapshot entirely or surface a partial-coverage warning.
+ */
+function computeCostUsd(agent, model, counts) {
+    const price = lookupPrice(agent, model);
+    if (!price)
+        return 0;
+    return ((counts.inputTokens / 1_000_000) * price.inputPerMTok +
+        (counts.outputTokens / 1_000_000) * price.outputPerMTok +
+        (counts.cacheReadTokens / 1_000_000) * price.cacheReadPerMTok +
+        (counts.cacheCreationTokens / 1_000_000) * price.cacheCreationPerMTok);
+}

package/dist/src/local-mcp-server/codex-token-adapter.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Codex Token Adapter — Issue #330 / R1.3
+ *
+ * Reads Codex CLI's per-session JSONL log at
+ * `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`, sums
+ * cumulative per-turn token counts, and converts to USD via the static
+ * price table.
+ *
+ * Verified against Codex CLI 0.125.0 session files. Token counts live at
+ * `event_msg.payload.info.total_token_usage.{input_tokens, output_tokens,
+ * cached_input_tokens, reasoning_output_tokens}`. Model lives on
+ * `turn_context.payload.model` (latest turn wins).
+ *
+ * Compliance: only counter values + model identifier exit this module.
+ * Prompt content, file paths, and other JSONL fields are explicitly
+ * dropped so PII never enters telemetry (C1).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureCodexSnapshot = captureCodexSnapshot;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const agent_token_prices_js_1 = require("./agent-token-prices.js");
+/**
+ * Read the Codex session file and produce a TokenSnapshot. Returns null
+ * (with optional log warning) if the file is missing, unreadable, or
+ * contains no token_count events.
+ */
+async function captureCodexSnapshot(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 250;
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    const file = opts.sessionFile ?? findLatestSessionFile(opts.sessionsRoot);
+    if (!file) {
+        opts.log?.('codex adapter: no session file found in ~/.codex/sessions');
+        return null;
+    }
+    let contents;
+    try {
+        contents = await fs.promises.readFile(file, 'utf8');
+    }
+    catch (err) {
+        opts.log?.(`codex adapter: cannot read ${file}: ${err.message}`);
+        return null;
+    }
+    let model = null;
+    let sessionId = null;
+    // Codex `total_token_usage` is cumulative; we use the highest seen
+    // (= most-recent cumulative) so partial reads during an active write
+    // don't regress.
+    let lastInput = 0;
+    let lastOutput = 0;
+    let lastCacheRead = 0;
+    let lastReasoningOutput = 0;
+    let foundAny = false;
+    const lines = contents.split('\n');
+    for (const line of lines) {
+        if (Date.now() > deadline) {
+            opts.log?.(`codex adapter: timeout after ${timeoutMs}ms; partial result`);
+            break;
+        }
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue; // skip malformed lines
+        }
+        if (!row || typeof row !== 'object')
+            continue;
+        // session_meta carries session id (model is not on this event).
+        if (row.type === 'session_meta' && row.payload && typeof row.payload === 'object') {
+            if (typeof row.payload.id === 'string')
+                sessionId = row.payload.id;
+            continue;
+        }
+        // turn_context carries the active model. Latest turn wins.
+        if (row.type === 'turn_context' && row.payload && typeof row.payload === 'object') {
+            if (typeof row.payload.model === 'string')
+                model = row.payload.model;
+            continue;
+        }
+        // event_msg with payload.type === 'token_count' carries cumulative usage.
+        if (row.type === 'event_msg' && row.payload && row.payload.type === 'token_count') {
+            const info = row.payload.info;
+            if (info && typeof info === 'object' && info.total_token_usage && typeof info.total_token_usage === 'object') {
+                const t = info.total_token_usage;
+                const i = numberOrZero(t.input_tokens);
+                const o = numberOrZero(t.output_tokens);
+                const cr = numberOrZero(t.cached_input_tokens);
+                const r = numberOrZero(t.reasoning_output_tokens);
+                if (i > lastInput)
+                    lastInput = i;
+                if (o > lastOutput)
+                    lastOutput = o;
+                if (cr > lastCacheRead)
+                    lastCacheRead = cr;
+                if (r > lastReasoningOutput)
+                    lastReasoningOutput = r;
+                foundAny = true;
+            }
+        }
+    }
+    if (!foundAny)
+        return null;
+    // Reasoning-output tokens are billed as output tokens by OpenAI today;
+    // fold them into the output count so the cost computation lines up
+    // with the user's bill.
+    const counts = {
+        inputTokens: lastInput,
+        outputTokens: lastOutput + lastReasoningOutput,
+        cacheReadTokens: lastCacheRead,
+        cacheCreationTokens: 0,
+    };
+    const costUsd = (0, agent_token_prices_js_1.computeCostUsd)('codex', model ?? undefined, counts);
+    // C1 — only the listed fields exit this module. No spread of row data,
+    // no prompt/content fields, no file paths.
+    return {
+        inputTokens: counts.inputTokens,
+        outputTokens: counts.outputTokens,
+        cacheReadTokens: counts.cacheReadTokens,
+        cacheCreationTokens: counts.cacheCreationTokens,
+        costUsd,
+        claudeSessionId: sessionId,
+        model,
+        capturedAt: new Date(),
+    };
+}
+function numberOrZero(v) {
+    return typeof v === 'number' && isFinite(v) ? v : 0;
+}
+/**
+ * Find the most recently modified `rollout-*.jsonl` under
+ * `~/.codex/sessions/YYYY/MM/DD/`. Returns null if the directory does not
+ * exist or is empty.
+ */
+function findLatestSessionFile(sessionsRoot) {
+    try {
+        const root = sessionsRoot ?? path.join(os.homedir(), '.codex', 'sessions');
+        if (!fs.existsSync(root))
+            return null;
+        let latestPath = null;
+        let latestMtime = 0;
+        // Walk YYYY / MM / DD / rollout-*.jsonl. Bounded to three levels so
+        // a stray symlink can't blow up the scan.
+        const years = safeReaddir(root);
+        for (const year of years) {
+            const yearDir = path.join(root, year);
+            if (!isDirectory(yearDir))
+                continue;
+            for (const month of safeReaddir(yearDir)) {
+                const monthDir = path.join(yearDir, month);
+                if (!isDirectory(monthDir))
+                    continue;
+                for (const day of safeReaddir(monthDir)) {
+                    const dayDir = path.join(monthDir, day);
+                    if (!isDirectory(dayDir))
+                        continue;
+                    for (const entry of safeReaddir(dayDir)) {
+                        if (!entry.endsWith('.jsonl'))
+                            continue;
+                        const full = path.join(dayDir, entry);
+                        try {
+                            const stat = fs.statSync(full);
+                            if (stat.mtimeMs > latestMtime) {
+                                latestMtime = stat.mtimeMs;
+                                latestPath = full;
+                            }
+                        }
+                        catch { /* skip unreadable */ }
+                    }
+                }
+            }
+        }
+        return latestPath;
+    }
+    catch {
+        return null;
+    }
+}
+function safeReaddir(dir) {
+    try {
+        return fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -222,12 +222,19 @@ function readFrontmatter(content) {
     }
     return frontmatter;
 }
+function isRetrospectiveSynthesized(value) {
+    if (value === undefined)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    return normalized !== 'false' && normalized !== 'no' && normalized !== '0' && normalized !== 'null';
+}
 function isUnsynthesizedRetrospective(filePath) {
     try {
         const content = (0, fs_1.readFileSync)(filePath, 'utf8');
         const frontmatter = readFrontmatter(content);
-        const synthesized = frontmatter.synthesized?.toLowerCase();
-        return synthesized !== 'true' && synthesized !== 'yes';
+        return !isRetrospectiveSynthesized(frontmatter.synthesized);
     }
     catch {
         return false;
@@ -340,7 +347,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
         if (l2PrefPresent)
             section += `\`${LEARNINGS_REL}/org-preferences.md\`  (all entries)\n`;
         if (l2CoachPresent)
-            section += `\`${LEARNINGS_REL}/org-manager-coaching.md\`  (all entries)\n`;
+            section += `\`${LEARNINGS_REL}/org-manager-coaching.md\`  (manager-facing; all entries)\n`;
         if (l2ValidatedPresent)
             section += `\`${LEARNINGS_REL}/org-validated-patterns.md\`  (entries above score threshold)\n`;
         const l2DormantTotal = (l2MistakeStats?.dormant || 0) + (l2ValidatedStats?.dormant || 0);
@@ -354,7 +361,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
         if (l1PrefPresent)
             section += `\`${LEARNINGS_REL}/${resolvedUserId}-preferences.md\`  (all entries)\n`;
         if (l1CoachPresent)
-            section += `\`${LEARNINGS_REL}/${resolvedUserId}-manager-coaching.md\`  (all entries)\n`;
+            section += `\`${LEARNINGS_REL}/${resolvedUserId}-manager-coaching.md\`  (manager-facing; all entries)\n`;
         if (l1MistakePresent)
             section += `\`${LEARNINGS_REL}/${resolvedUserId}-mistake-patterns.md\`  (entries above score threshold)\n`;
         if (l1ValidatedPresent)
@@ -371,7 +378,7 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
             section += `${l0CoachingCount} coaching moment${l0CoachingCount !== 1 ? 's' : ''} in \`${LEARNINGS_REL}/raw/${resolvedUserId}-*\`\n`;
         }
         if (l0RetroCount > 0) {
-            section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} in \`docs/retrospectives/${resolvedUserId}-*\` with \`synthesized: false\` or missing\n`;
+            section += `${l0RetroCount} retrospective${l0RetroCount !== 1 ? 's' : ''} in \`docs/retrospectives/${resolvedUserId}-*\` with unsynthesized or missing \`synthesized\` frontmatter\n`;
         }
         section += '\n';
     }
@@ -381,20 +388,26 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     const backlogTriggered = totalL0 >= BACKLOG_MIN || (oldestAgeDays >= OLDEST_AGE_DAYS_TRIGGER && totalL0 > 0);
     if (forJob) {
         if (hasL2 || hasL1) {
-            section += 'Use the relevant patterns, preferences, and coaching signals in this job.\n';
+            section += 'Use the relevant patterns and preferences in this job.\n';
+            if (l1CoachPresent || l2CoachPresent) {
+                section += 'Treat manager-coaching as feedback for how the manager should continue or improve managing AI, not as agent instruction.\n';
+            }
         }
         if (backlogTriggered) {
             section += '\n';
-            section += `Warning: ${totalL0} unprocessed signals pending. Consider running \`end-of-day-debrief\` before starting today's work.\n`;
+            section += `Warning: ${totalL0} unprocessed signals pending. Consider running \`sleep-on-learnings\` before starting today's work.\n`;
             section += renderBacklogDetail(oldestAgeDays, agingRisk);
         }
     }
     else {
         section += 'Use this synthesized learning context throughout the session.\n';
+        if (l1CoachPresent || l2CoachPresent) {
+            section += 'Manager-coaching entries are manager-facing feedback, not instructions for the AI to follow.\n';
+        }
         if (backlogTriggered) {
             section += '\n';
             section += `Warning: synthesis overdue with ${totalL0} unprocessed signals.\n`;
-            section += 'Run `end-of-day-debrief` before starting today\'s work.\n';
+            section += 'Run `sleep-on-learnings` before starting today\'s work.\n';
             section += renderBacklogDetail(oldestAgeDays, agingRisk);
         }
     }

package/dist/src/local-mcp-server/otlp-metrics-receiver.js

@@ -257,6 +257,12 @@ function startOtlpReceiver(log) {
  * Stop the OTLP receiver and clear stored snapshots.
  */
 function stopOtlpReceiver(server) {
-    server.close();
+    try {
+        server.close();
+    }
+    catch {
+        // The receiver may have failed to bind because another FRAIM proxy owns
+        // the port. In that case there is no local listener to close.
+    }
     snapshots.clear();
 }

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

@@ -33,6 +33,7 @@ const quality_evidence_1 = require("../core/quality-evidence");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 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");
 /**
  * Handle template substitution logic separately for better testability
@@ -401,6 +402,7 @@ class FraimLocalMCPServer {
         this.repoInfo = null;
         this.engine = null;
         this.otlpServer = null;
+        this.isShutdown = false;
         this.writer = writer || process.stdout.write.bind(process.stdout);
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = this.loadApiKey();
@@ -421,6 +423,16 @@ class FraimLocalMCPServer {
         // Start OTLP metrics receiver for Claude Code token telemetry
         this.otlpServer = (0, otlp_metrics_receiver_js_1.startOtlpReceiver)((msg) => this.log(`📊 ${msg}`));
     }
+    shutdown() {
+        if (this.isShutdown)
+            return;
+        this.isShutdown = true;
+        this.usageCollector.shutdown();
+        if (this.otlpServer?.server) {
+            (0, otlp_metrics_receiver_js_1.stopOtlpReceiver)(this.otlpServer.server);
+            this.otlpServer = null;
+        }
+    }
     /**
      * Load API key from environment variable or user config file
      * Priority: FRAIM_API_KEY env var > ~/.fraim/config.json
@@ -617,9 +629,10 @@ class FraimLocalMCPServer {
                 // Fall back to config if git fails
                 repoUrl = this.config?.repository?.url || '';
             }
+            const workspaceLabel = (0, path_1.parse)(projectDir).base || 'workspace';
             if (!repoUrl) {
-                this.log('No git repository found and no config available');
-                return null;
+                this.log(`No git repository found; falling back to workspace folder label: ${workspaceLabel}`);
+                repoUrl = workspaceLabel;
             }
             // Parse repository identity from URL
             let name = '';
@@ -646,6 +659,9 @@ class FraimLocalMCPServer {
                 name = segments[segments.length - 1] || '';
                 namespace = segments.slice(0, -1).join('/');
             }
+            else if (!repoUrl.includes('/') && !repoUrl.includes('\\') && !repoUrl.includes('://')) {
+                name = repoUrl;
+            }
             else if (this.config?.repository) {
                 // Fall back to config if URL parsing fails
                 owner = this.config.repository.owner || '';
@@ -1431,6 +1447,33 @@ class FraimLocalMCPServer {
             projectPath: `${issueTracking.namespace}/${issueTracking.name}`
         };
     }
+    hasRemoteRepoLocator(value) {
+        if (typeof value !== 'string')
+            return false;
+        return /^[a-z]+:\/\//i.test(value) || /^[^@\s]+@[^:\s]+:/i.test(value);
+    }
+    mergeRepoContexts(agentRepo, detectedRepo) {
+        const normalizedAgent = this.normalizeRepoContext(agentRepo);
+        const normalizedDetected = this.normalizeRepoContext(detectedRepo);
+        if (!normalizedAgent)
+            return normalizedDetected;
+        if (!normalizedDetected)
+            return normalizedAgent;
+        const agentHasRemoteUrl = this.hasRemoteRepoLocator(normalizedAgent.url);
+        const detectedHasRemoteUrl = this.hasRemoteRepoLocator(normalizedDetected.url);
+        // Preserve an explicit agent-supplied remote repository when local auto-detection
+        // only found a workspace label or other non-remote fallback.
+        if (agentHasRemoteUrl && !detectedHasRemoteUrl) {
+            return this.normalizeRepoContext({
+                ...normalizedDetected,
+                ...normalizedAgent
+            });
+        }
+        return this.normalizeRepoContext({
+            ...normalizedAgent,
+            ...normalizedDetected
+        });
+    }
     /**
      * Internal method to perform the actual proxy request to the remote server.
      * This method does NOT inject raw: true, as it is used for both top-level
@@ -1452,11 +1495,7 @@ class FraimLocalMCPServer {
                 // REQUIRED: Auto-detect and inject repo info
                 const detectedRepo = this.detectRepoInfo();
                 if (detectedRepo) {
-                    args.repo = {
-                        ...args.repo, // Agent values as fallback
-                        ...detectedRepo // Detected values override (always win)
-                    };
-                    args.repo = this.normalizeRepoContext(args.repo);
+                    args.repo = this.mergeRepoContexts(args.repo, detectedRepo);
                     const repoLabel = args.repo.owner ? `${args.repo.owner}/${args.repo.name}` : args.repo.name;
                     this.log(`[req:${requestId}] Auto-detected and injected repo info: ${repoLabel}`);
                 }
@@ -1503,6 +1542,11 @@ class FraimLocalMCPServer {
                     this.engine.setMachineInfo(this.machineInfo);
                     this.engine.setRepoInfo(this.repoInfo);
                 }
+                // Issue #330: capture agent identity on the usage collector so every
+                // queued event is attributed without re-reading args downstream.
+                if (this.usageCollector && this.agentInfo) {
+                    this.usageCollector.setAgent(this.agentInfo.name ?? null, this.agentInfo.model ?? null);
+                }
                 // In a proxy setup, the remote server resolves the API key ID during event upload.
                 // No local resolution needed.
                 // Update the request with injected info
@@ -1884,13 +1928,11 @@ class FraimLocalMCPServer {
                 this.log(`⚠️ Failed to upload usage data: ${error.message}`);
             });
         }, 60000); // Upload every minute
+        uploadInterval.unref?.();
         // Clean up interval on shutdown
         const cleanup = () => {
             clearInterval(uploadInterval);
-            this.usageCollector.shutdown();
-            if (this.otlpServer?.server) {
-                (0, otlp_metrics_receiver_js_1.stopOtlpReceiver)(this.otlpServer.server);
-            }
+            this.shutdown();
         };
         process.stdin.on('data', async (chunk) => {
             buffer += chunk;
@@ -1989,17 +2031,28 @@ class FraimLocalMCPServer {
                 const afterCount = this.usageCollector.getEventCount();
                 if (afterCount > beforeCount) {
                     this.log(`📊 ✅ Event queued successfully (queue: ${afterCount})`);
-                    // Fetch token snapshot from OTLP receiver for seekMentoring calls
+                    // Issue #330: pluggable token capture by agent.
                     if (toolName === 'seekMentoring') {
                         try {
-                            const snapshot = await (0, otlp_metrics_receiver_js_1.fetchSnapshot)(undefined, (msg) => this.log(`📊 ${msg}`));
-                            if (snapshot) {
-                                this.usageCollector.attachTokenSnapshot(snapshot);
-                                this.log(`📊 🔢 Token snapshot attached (input=${snapshot.inputTokens}, output=${snapshot.outputTokens}, session=${snapshot.claudeSessionId})`);
+                            const agentName = this.agentInfo?.name;
+                            const agentModel = this.agentInfo?.model;
+                            const adapter = (0, token_adapter_registry_js_1.resolveTokenAdapter)(agentName);
+                            const result = await adapter.capture({
+                                agent: agentName,
+                                model: agentModel,
+                                log: (msg) => this.log(`📊 ${msg}`),
+                            });
+                            if (result.snapshot) {
+                                this.usageCollector.attachTokenSnapshot(result.snapshot);
+                                this.log(`📊 🔢 Token snapshot attached via ${adapter.id} adapter (input=${result.snapshot.inputTokens}, output=${result.snapshot.outputTokens})`);
+                            }
+                            else if (result.reason) {
+                                this.usageCollector.attachCaptureUnavailable(result.reason);
+                                this.log(`📊 ℹ️ Token capture unavailable (${result.reason}) for adapter ${adapter.id}`);
                             }
                         }
                         catch (err) {
-                            this.log(`📊 ⚠️ Token snapshot fetch failed (non-blocking): ${err.message}`);
+                            this.log(`📊 ⚠️ Token snapshot capture failed (non-blocking): ${err.message}`);
                         }
                     }
                 }

package/dist/src/local-mcp-server/token-adapter-registry.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Token Adapter Registry — Issue #330 / R1.1, R1.4, R1.5
+ *
+ * Pluggable dispatch by agent name. Each adapter implements
+ * `capture(ctx)` returning either a `TokenSnapshot` or `null` plus a
+ * typed reason (`tokenCaptureUnavailableReason`) so the UI can explain
+ * coverage gaps.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTokenAdapter = resolveTokenAdapter;
+const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
+const codex_token_adapter_js_1 = require("./codex-token-adapter.js");
+const claudeCodeAdapter = {
+    id: 'claude-code',
+    async capture(ctx) {
+        const snap = await (0, otlp_metrics_receiver_js_1.fetchSnapshot)(ctx.agentSessionId, ctx.log);
+        if (snap)
+            return { snapshot: snap };
+        return { snapshot: null, reason: 'otlp_receiver_unreachable' };
+    },
+};
+const codexAdapter = {
+    id: 'codex',
+    async capture(ctx) {
+        try {
+            const snap = await (0, codex_token_adapter_js_1.captureCodexSnapshot)({ log: ctx.log });
+            if (snap)
+                return { snapshot: snap };
+            return { snapshot: null, reason: 'codex_session_log_not_found' };
+        }
+        catch (err) {
+            ctx.log?.(`codex adapter threw: ${err.message}`);
+            return { snapshot: null, reason: 'codex_adapter_error' };
+        }
+    },
+};
+const nullAdapterFor = (canonicalAgent) => ({
+    id: 'null',
+    async capture() {
+        return { snapshot: null, reason: `agent_not_supported:${canonicalAgent}` };
+    },
+});
+/**
+ * Map of canonical agent ids to adapters. Keys are lower-cased.
+ * Aliases (e.g. "claude" → claude-code) are handled in the resolver below.
+ */
+const ADAPTERS = {
+    'claude-code': claudeCodeAdapter,
+    'claude': claudeCodeAdapter,
+    'codex': codexAdapter,
+};
+/**
+ * Resolve an adapter by agent.name (case-insensitive). Always returns
+ * an adapter — falls back to a null adapter that reports
+ * "agent_not_supported:<name>".
+ */
+function resolveTokenAdapter(agentName) {
+    const canonical = (agentName || 'unknown').toLowerCase().trim();
+    const adapter = ADAPTERS[canonical];
+    if (adapter)
+        return adapter;
+    return nullAdapterFor(canonical || 'unknown');
+}