@minhpnq1807/contextos 0.1.3 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.6
+
+- Adds a transparent stdio MCP telemetry proxy that records `tools/call` events while forwarding requests to the original MCP server.
+- `ctx install` now wraps supported local MCP servers, including `code-review-graph` and `agentmemory`, so runtime-only tool rules can be measured from real MCP usage.
+
+## 0.1.5
+
+- Sanitizes stale Stop reports at display time so previously recorded system-user rules no longer appear in `ctx report` or `ctx evidence` after upgrading.
+- Filters system-user rules again inside the Stop hook to protect reports created from older prompt contexts.
+
+## 0.1.4
+
+- Filters host/session user rules such as `sudo -u user`, `sudo su - user`, and "commands must run as user X" before scoring and injection.
+- Prevents system-user setup instructions from inflating `unknown` outcomes or skewing ContextOS efficiency reports.
+
 ## 0.1.3
 
 - Separates runtime prompt/report/stats files per workspace under `~/.ctx/contextos/workspaces/<workspace-id>`.

package/README.md

@@ -53,7 +53,7 @@ With ContextOS, each prompt gets a compact block:
 ```text
 ## Critical ContextOS rules
 - Use code-review-graph before reading files.
-- All shell commands must run as minh_dev.
+- Check upload moderation flows before editing approval code.
 
 ## Suggested files to check
 - services/content-service/src/infrastructure/services/content-moderation.service.ts
@@ -66,6 +66,7 @@ With ContextOS, each prompt gets a compact block:
 - Registers a `ctx-mcp` MCP server that owns model loading and semantic scoring.
 - Reads the active `AGENTS.md` chain for the current workspace.
 - Scores rules by relevance to the user prompt.
+- Filters host/session setup rules such as "run commands as user X" or `sudo -u user` because they are environment instructions, not project guidance.
 - Finds likely relevant files with a hybrid retriever:
   - first, local prompt/file heuristics create seed candidates;
   - then, if `.code-review-graph/graph.db` exists, ContextOS queries `code-review-graph` semantic search and re-ranks graph-backed matches;
@@ -104,6 +105,7 @@ node bin/ctx.js install
 3. Downloads and caches the required local MiniLM embedding model under `~/.ctx/contextos/models`.
 4. Warms `~/.ctx/contextos/embeddings.db` for AGENTS rules and project file paths.
 5. Registers the `ctx-mcp` MCP server and merges ContextOS global hooks into `$CODEX_HOME/hooks.json`.
+6. Wraps supported local MCP servers, currently `code-review-graph` and `agentmemory`, with a transparent telemetry proxy so `tools/call` events can be measured.
 
 Restart Codex after installing.
 
@@ -288,7 +290,9 @@ unknown  = the rule was relevant, but the diff does not prove either way
 
 For runtime-only rules, ContextOS also checks `telemetry.jsonl` for hook-visible tool names, MCP server names, and command metadata. A rule like "use code-review-graph before reading files" can be marked `followed` when telemetry contains a matching `code-review-graph` signal.
 
-Example `unknown`: a rule says shell commands must run as a specific OS user, but neither git diff nor hook telemetry records that user identity. ContextOS cannot prove the rule was followed from available evidence alone.
+`ctx install` wraps supported stdio MCP servers with a transparent proxy. The proxy forwards MCP JSON-RPC unchanged, but records `tools/call` requests such as `code-review-graph.detect_changes_tool` to workspace telemetry. This is what lets ContextOS prove runtime rules that cannot be seen in git diff.
+
+Host/session setup rules such as "run shell commands as user X", `sudo su - user`, `sudo -i -u user`, and `sudo -u user` are filtered before scoring. They are not injected and do not count toward `unknown` outcomes because they describe the agent runtime environment rather than project behavior.
 
 ## Development
 

package/bin/ctx.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 
 import { readAgentsChain } from "../plugins/ctx/lib/reader.js";
-import { parseRules, scoreRules } from "../plugins/ctx/lib/analyzer.js";
+import { filterActionableRules, parseRules, scoreRules } from "../plugins/ctx/lib/analyzer.js";
 import { scheduleContext } from "../plugins/ctx/lib/scheduler.js";
 import { formatEvidence, formatReport } from "../plugins/ctx/lib/reporter.js";
 import { installGlobalHooks } from "../plugins/ctx/lib/global-hooks.js";
@@ -14,6 +14,7 @@ import { modelCacheDir, warmRuleEmbeddings } from "../plugins/ctx/lib/embedding-
 import { warmFileEmbeddings } from "../plugins/ctx/lib/file-embedding-retriever.js";
 import { scoreContext } from "../plugins/ctx/lib/score-context.js";
 import { defaultDataRoot, workspaceDataDir, workspaceMarkerPath } from "../plugins/ctx/lib/workspace-data.js";
+import { installMcpTelemetryProxies } from "../plugins/ctx/lib/mcp-proxy-install.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -101,6 +102,7 @@ async function install({ copy = false, inject = true } = {}) {
   runCodex(["plugin", "marketplace", "add", marketplaceRoot]);
   runCodex(["plugin", "add", "ctx@contextos"]);
   runCodex(["mcp", "add", "ctx-mcp", "--", "node", path.join(marketplaceRoot, "plugins", "ctx", "mcp", "server.js")]);
+  const proxyResult = installMcpTelemetryProxies({ codexHome: codexHome(), marketplaceRoot });
   const hooksPath = installGlobalHooks({ codexHome: codexHome(), marketplaceRoot, injectPromptContext: inject });
 
   console.log("Preparing required local embedding model...");
@@ -109,6 +111,7 @@ async function install({ copy = false, inject = true } = {}) {
   console.log(`Stable marketplace root: ${marketplaceRoot}`);
   console.log(`Installed ContextOS global hooks to ${hooksPath}`);
   console.log("Installed ctx-mcp MCP server.");
+  console.log(`MCP telemetry proxies: ${proxyResult.wrapped.length ? proxyResult.wrapped.map((item) => item.name).join(", ") : "none changed"}`);
   console.log(`Embedding model cache: ${modelCacheDir(contextOSDataDir())}`);
   console.log(`Embedding vectors cache: ${warmResult.cachePath}`);
   console.log(`File path embeddings warmed: ${warmResult.fileCount || 0}`);
@@ -222,7 +225,7 @@ async function debug(task) {
 async function warmEmbeddings(task) {
   const cwd = process.cwd();
   const merged = readAgentsChain({ cwd });
-  const rules = scoreRules(parseRules(merged.content), task, []);
+  const rules = scoreRules(filterActionableRules(parseRules(merged.content)), task, []);
   const result = await warmRuleEmbeddings({
     rules,
     task,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex.",
   "type": "module",
   "bin": {

package/plugins/ctx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx",
-  "version": "0.1.0",
+  "version": "0.1.6",
   "description": "Inject task-relevant AGENTS.md rules into Codex through plugin hooks.",
   "author": {
     "name": "ContextOS"

package/plugins/ctx/lib/analyzer.js

@@ -48,6 +48,20 @@ const SEMANTIC_ALIASES = {
 
 const MODERATION_TOKENS = new Set(["moderation", "moderate", "content-moderation", "approval", "approved", "reject", "rejected", "needs_review"]);
 
+const SYSTEM_USER_RULE_PATTERNS = [
+  /\ball\s+shell\s+commands?\s+must\s+run\s+as\b/i,
+  /\bcommands?\s+must\s+run\s+as\b/i,
+  /\bstrictly\s+follow\s+this\s+sequence\b/i,
+  /\bswitch\s+the\s+user\s+context\b/i,
+  /\bdo\s+not\s+prefix\b.*\bsudo\s+-u\b/i,
+  /\bsudo\s+su\s+-\s*[a-z_][a-z0-9_-]*\b/i,
+  /\bsudo\s+-i\s+-u\s+[a-z_][a-z0-9_-]*\b/i,
+  /\bsudo\s+-u\s+[a-z_][a-z0-9_-]*\b/i,
+  /\bsu\s+-\s+[a-z_][a-z0-9_-]*\b/i,
+  /[/\\]\.codex[/\\]RTK\.md\b/i,
+  /\bminh_dev\b/i
+];
+
 export function tokenize(value) {
   const normalized = String(value || "")
     .toLowerCase()
@@ -138,6 +152,17 @@ export function parseRules(markdown) {
   return dedupeRules(rules);
 }
 
+export function filterActionableRules(rules = []) {
+  return rules
+    .filter((rule) => !isSystemUserRule(rule))
+    .map((rule, index) => ({ ...rule, id: `r${index + 1}`, originalOrder: index }));
+}
+
+export function isSystemUserRule(rule) {
+  const content = typeof rule === "string" ? rule : rule?.content;
+  return SYSTEM_USER_RULE_PATTERNS.some((pattern) => pattern.test(String(content || "")));
+}
+
 function dedupeRules(rules) {
   const seen = new Set();
   return rules.filter((rule) => {

package/plugins/ctx/lib/mcp-proxy-install.js

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_TARGETS = new Set(["code-review-graph", "agentmemory"]);
+
+export function installMcpTelemetryProxies({ codexHome, marketplaceRoot, targets = DEFAULT_TARGETS } = {}) {
+  const configPath = path.join(codexHome, "config.toml");
+  if (!fs.existsSync(configPath)) return { wrapped: [], skipped: [], configPath };
+
+  const original = fs.readFileSync(configPath, "utf8");
+  const proxyPath = path.join(marketplaceRoot, "plugins", "ctx", "mcp", "proxy.js");
+  const result = rewriteMcpTelemetryProxies(original, { proxyPath, targets });
+  if (result.content !== original) {
+    fs.writeFileSync(configPath, result.content, "utf8");
+  }
+  return { ...result, configPath };
+}
+
+export function rewriteMcpTelemetryProxies(toml, { proxyPath, targets = DEFAULT_TARGETS } = {}) {
+  const lines = String(toml || "").split(/\r?\n/);
+  const sections = findMcpServerSections(lines);
+  const wrapped = [];
+  const skipped = [];
+
+  for (const section of sections.reverse()) {
+    if (!targets.has(section.name)) {
+      skipped.push({ name: section.name, reason: "not-targeted" });
+      continue;
+    }
+
+    const body = lines.slice(section.start + 1, section.end);
+    const command = findStringValue(body, "command");
+    const args = findArrayValue(body, "args") || [];
+    if (!command) {
+      skipped.push({ name: section.name, reason: "missing-command" });
+      continue;
+    }
+    if (command === "node" && args[0] === proxyPath) {
+      skipped.push({ name: section.name, reason: "already-wrapped" });
+      continue;
+    }
+
+    const nextBody = replaceOrInsertServerField(
+      replaceOrInsertServerField(body, "command", tomlString("node")),
+      "args",
+      tomlArray([proxyPath, "--name", section.name, "--", command, ...args])
+    );
+    lines.splice(section.start + 1, section.end - section.start - 1, ...nextBody);
+    wrapped.push({ name: section.name, command, args });
+  }
+
+  return { content: lines.join("\n"), wrapped: wrapped.reverse(), skipped: skipped.reverse() };
+}
+
+function findMcpServerSections(lines) {
+  const sections = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^\[mcp_servers\.([^\].]+)\]\s*$/);
+    if (!match) continue;
+    let end = lines.length;
+    for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+      if (/^\[/.test(lines[cursor])) {
+        end = cursor;
+        break;
+      }
+    }
+    sections.push({ name: unquoteTomlKey(match[1]), start: index, end });
+  }
+  return sections;
+}
+
+function replaceOrInsertServerField(body, key, value) {
+  const next = [...body];
+  const index = next.findIndex((line) => new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`).test(line));
+  const line = `${key} = ${value}`;
+  if (index >= 0) next[index] = line;
+  else next.unshift(line);
+  return next;
+}
+
+function findStringValue(lines, key) {
+  const line = lines.find((item) => new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`).test(item));
+  if (!line) return null;
+  const match = line.match(/=\s*"((?:\\.|[^"\\])*)"/);
+  return match ? unescapeTomlString(match[1]) : null;
+}
+
+function findArrayValue(lines, key) {
+  const line = lines.find((item) => new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`).test(item));
+  if (!line) return null;
+  const arrayMatch = line.match(/=\s*\[(.*)\]\s*$/);
+  if (!arrayMatch) return null;
+  const values = [];
+  const pattern = /"((?:\\.|[^"\\])*)"/g;
+  let match;
+  while ((match = pattern.exec(arrayMatch[1]))) values.push(unescapeTomlString(match[1]));
+  return values;
+}
+
+function tomlArray(values) {
+  return `[${values.map(tomlString).join(", ")}]`;
+}
+
+function tomlString(value) {
+  return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function unescapeTomlString(value) {
+  return String(value).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+}
+
+function unquoteTomlKey(value) {
+  return value.replace(/^"|"$/g, "");
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/plugins/ctx/lib/reporter.js

@@ -1,7 +1,10 @@
+import { isSystemUserRule } from "./analyzer.js";
+
 export function buildReport({ cwd, prompt, relevantFiles, scheduled, gitSnapshot, compliance, runtimeEvidence }) {
-  const followed = compliance.filter((item) => item.status === "followed");
-  const ignored = compliance.filter((item) => item.status === "ignored");
-  const unknown = compliance.filter((item) => item.status === "unknown");
+  const actionableCompliance = compliance.filter((item) => !isSystemUserRule(item.rule));
+  const followed = actionableCompliance.filter((item) => item.status === "followed");
+  const ignored = actionableCompliance.filter((item) => item.status === "ignored");
+  const unknown = actionableCompliance.filter((item) => item.status === "unknown");
   const measured = followed.length + ignored.length;
   const efficiencyScore = measured ? Math.round((followed.length / measured) * 100) : null;
 
@@ -24,6 +27,7 @@ export function buildReport({ cwd, prompt, relevantFiles, scheduled, gitSnapshot
 }
 
 export function formatReport(report) {
+  report = sanitizeReport(report);
   const lines = [];
   lines.push("ContextOS report");
   lines.push(`Efficiency: ${report.efficiencyScore == null ? "unknown" : `${report.efficiencyScore}%`}`);
@@ -55,6 +59,7 @@ export function formatReport(report) {
 }
 
 export function formatEvidence(report) {
+  report = sanitizeReport(report);
   const lines = [];
   lines.push("ContextOS evidence");
   lines.push(`Prompt: ${report.prompt || "(empty)"}`);
@@ -119,3 +124,20 @@ function summarizeRuntimeEvidence(runtimeEvidence = {}) {
     sources: (runtimeEvidence.sources || []).slice(0, 10)
   };
 }
+
+function sanitizeReport(report = {}) {
+  const followed = (report.followed || []).filter((item) => !isSystemUserRule(item.rule));
+  const ignored = (report.ignored || []).filter((item) => !isSystemUserRule(item.rule));
+  const unknown = (report.unknown || []).filter((item) => !isSystemUserRule(item.rule));
+  const measured = followed.length + ignored.length;
+  return {
+    ...report,
+    injectedRuleCount: followed.length + ignored.length + unknown.length,
+    followed,
+    ignored,
+    unknown,
+    measuredRuleCount: measured,
+    unknownRuleCount: unknown.length,
+    efficiencyScore: measured ? Math.round((followed.length / measured) * 100) : null
+  };
+}

package/plugins/ctx/lib/score-context.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 
 import { readAgentsChain } from "./reader.js";
-import { parseRules, scoreRules, findRelevantFiles } from "./analyzer.js";
+import { filterActionableRules, parseRules, scoreRules, findRelevantFiles } from "./analyzer.js";
 import { enhanceRuleScoresWithEmbeddings } from "./embedding-scorer.js";
 
 export async function scoreContext({
@@ -15,7 +15,8 @@ export async function scoreContext({
 } = {}) {
   const started = Date.now();
   const merged = readAgentsChain({ cwd });
-  const parsedRules = parseRules(merged.content);
+  const rawRules = parseRules(merged.content);
+  const parsedRules = filterActionableRules(rawRules);
   const baseScoredRules = scoreRules(parsedRules, prompt, openFiles);
   const embedding = await enhanceRuleScoresWithEmbeddings(baseScoredRules, prompt, {
     dataDir,
@@ -47,6 +48,7 @@ export async function scoreContext({
       model: embedding.model,
       cachePath: embedding.cachePath,
       rulesParsed: parsedRules.length,
+      rulesFiltered: rawRules.length - parsedRules.length,
       rulesInjected: scoredRules.filter((rule) => Number(rule.score || 0) >= 0.1).length,
       filesSuggested: suggestedFiles.length,
       sources: merged.sources.map((source) => path.relative(cwd, source))

package/plugins/ctx/lib/stop-hook.js

@@ -4,14 +4,27 @@ import { appendJsonLine, readJsonFile, writeJsonFile } from "./fs-utils.js";
 import { readGitSnapshot, checkCompliance } from "./measure.js";
 import { buildReport, formatReport } from "./reporter.js";
 import { loadRuntimeEvidence } from "./telemetry.js";
+import { filterActionableRules } from "./analyzer.js";
 
 export function handleStopPayload(payload, { contextPath, reportPath, historyPath, telemetryPath } = {}) {
   const cwd = payload.cwd || payload.working_directory || process.cwd();
   const promptContext = contextPath && fs.existsSync(contextPath) ? readJsonFile(contextPath) : null;
-  const scheduledRules = [
+  const rawScheduledRules = [
     ...(promptContext?.scheduled?.highRules || []),
     ...(promptContext?.scheduled?.midRules || [])
   ];
+  const scheduledRules = filterActionableRules(rawScheduledRules);
+  const scheduled = promptContext?.scheduled
+    ? {
+      ...promptContext.scheduled,
+      highRules: filterActionableRules(promptContext.scheduled.highRules || []),
+      midRules: filterActionableRules(promptContext.scheduled.midRules || []),
+      droppedRules: [
+        ...(promptContext.scheduled.droppedRules || []),
+        ...rawScheduledRules.filter((rule) => !scheduledRules.some((item) => item.content === rule.content && item.sourcePath === rule.sourcePath))
+      ]
+    }
+    : null;
   const gitSnapshot = readGitSnapshot({ cwd });
   const runtimeEvidence = loadRuntimeEvidence({
     telemetryPath,
@@ -28,7 +41,7 @@ export function handleStopPayload(payload, { contextPath, reportPath, historyPat
     cwd,
     prompt: promptContext?.prompt || "",
     relevantFiles: promptContext?.relevantFiles || [],
-    scheduled: promptContext?.scheduled || null,
+    scheduled,
     gitSnapshot,
     compliance,
     runtimeEvidence

package/plugins/ctx/mcp/proxy.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+import { appendTelemetry } from "../lib/telemetry.js";
+import { workspaceDataDir } from "../lib/workspace-data.js";
+
+const { serverName, command, args } = parseArgs(process.argv.slice(2));
+const cwd = process.cwd();
+const telemetryPath = path.join(workspaceDataDir({ cwd }), "telemetry.jsonl");
+let inspectBuffer = "";
+
+const child = spawn(command, args, {
+  cwd,
+  env: process.env,
+  stdio: ["pipe", "pipe", "pipe"]
+});
+
+process.stdin.on("data", (chunk) => {
+  inspectClientChunk(chunk);
+  child.stdin.write(chunk);
+});
+
+process.stdin.on("end", () => {
+  child.stdin.end();
+});
+
+child.stdout.on("data", (chunk) => {
+  process.stdout.write(chunk);
+});
+
+child.stderr.on("data", (chunk) => {
+  process.stderr.write(chunk);
+});
+
+child.on("error", (error) => {
+  process.stderr.write(`contextos mcp proxy failed to start ${serverName}: ${error?.message || String(error)}\n`);
+  process.exitCode = 1;
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});
+
+function inspectClientChunk(chunk) {
+  inspectBuffer += chunk.toString("utf8");
+  const lines = inspectBuffer.split(/\r?\n/);
+  inspectBuffer = lines.pop() || "";
+  for (const line of lines.filter(Boolean)) {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (message?.method !== "tools/call") continue;
+    const toolName = message.params?.name || "unknown";
+    appendTelemetry({
+      telemetryPath,
+      event: "McpToolCall",
+      payload: {
+        cwd,
+        mcp: serverName,
+        server: serverName,
+        toolName: `${serverName}.${toolName}`,
+        tool: toolName,
+        method: message.method
+      }
+    });
+  }
+}
+
+function parseArgs(argv) {
+  const separator = argv.indexOf("--");
+  if (separator < 0) usage();
+
+  const before = argv.slice(0, separator);
+  const after = argv.slice(separator + 1);
+  const nameIndex = before.indexOf("--name");
+  const serverName = nameIndex >= 0 ? before[nameIndex + 1] : null;
+  const command = after[0];
+  const args = after.slice(1);
+
+  if (!serverName || !command) usage();
+  return { serverName, command, args };
+}
+
+function usage() {
+  process.stderr.write("Usage: node proxy.js --name <mcp-server-name> -- <command> [...args]\n");
+  process.exit(2);
+}