ctxloom-pro 1.4.0 → 1.5.0

package/README.md

@@ -47,7 +47,7 @@ The full first-run flow is **one install + one trial + one init per project.** E
 npm install -g ctxloom-pro
 ```
 
-> **For local trial / dev use the unpinned command above is fine.** For unattended CI usage, pin to the exact version (`ctxloom-pro@1.4.0`) so future CLI releases don't silently desync your agent-spec coverage — see the workflow example below.
+> **For local trial / dev use the unpinned command above is fine.** For unattended CI usage, pin to the exact version (`ctxloom-pro@1.5.0`) so future CLI releases don't silently desync your agent-spec coverage — see the workflow example below.
 
 ### 2 — Start your free trial (once per email)
 
@@ -346,7 +346,7 @@ jobs:
       # Exact pin (not `@^1`) so future CLI releases that add/remove MCP
       # tools don't silently desync your reviewer-agent specs. Bump on
       # every release; see CHANGELOG.md for the live version table.
-      - run: npm install -g ctxloom-pro@1.4.0
+      - run: npm install -g ctxloom-pro@1.5.0
       - run: ctxloom index
       - run: ctxloom rules check --json
 ```

package/apps/dashboard/dist/server/index.js

@@ -8288,9 +8288,6 @@ var ProjectRootField = external_exports.string().optional().describe(PROJECT_ROO
 // ../../packages/core/src/tools/registry.ts
 init_logger();
 
-// ../../packages/core/src/tools/search.ts
-init_embedder();
-
 // ../../packages/core/src/budget/budget.ts
 init_logger();
 
@@ -8301,7 +8298,21 @@ import os2 from "os";
 import path16 from "path";
 var DEFAULT_TELEMETRY_DIR = path16.join(os2.homedir(), ".ctxloom", "telemetry");
 
+// ../../packages/core/src/budget/learnedSuggestions.ts
+var CACHE_TTL_MS = 60 * 60 * 1e3;
+
+// ../../packages/core/src/budget/taskBudget.ts
+var OVER_BUDGET_ARG_OVERRIDES = Object.freeze({
+  // Budget-surface tools (the 12 source-returning ones).
+  max_response_tokens: 200,
+  response_format: "skeleton",
+  on_budget_exceeded: "skeleton",
+  // Tools with detail_level (hub_nodes, bridge_nodes, etc).
+  detail_level: "minimal"
+});
+
 // ../../packages/core/src/tools/search.ts
+init_embedder();
 var Schema = external_exports.object({
   query: external_exports.string().describe("Search query \u2014 natural language or code fragment"),
   limit: external_exports.number().max(100).optional().default(10).describe("Maximum results to return"),
@@ -11441,7 +11452,7 @@ function resolveTelemetryLevel() {
 }
 var TELEMETRY_LEVEL = resolveTelemetryLevel();
 var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
-var CTXLOOM_VERSION = "1.4.0".length > 0 ? "1.4.0" : "dev";
+var CTXLOOM_VERSION = "1.5.0".length > 0 ? "1.5.0" : "dev";
 var POSTHOG_HOST = "https://eu.i.posthog.com";
 var POSTHOG_KEY = process.env["POSTHOG_API_KEY"] ?? (true ? "phc_CiDkmFLcZ2K6uCpcoSUQLmFrnnUvsyXGhSxopX5TVKE6" : "");
 var SENTRY_DSN = process.env["SENTRY_DSN"] ?? (true ? "https://81c94a0f04a8e242dee493ac1e17f733@o4508531702497280.ingest.de.sentry.io/4511256875368528" : "");
@@ -11601,6 +11612,72 @@ import fs31 from "fs";
 import path39 from "path";
 
 // ../../packages/core/src/install/templates.ts
+var RULES_BLOCK_CONTENT = `## MCP Tools: ctxloom
+
+**IMPORTANT: This project has a knowledge graph. ALWAYS use the
+ctxloom MCP tools BEFORE Grep/Glob/Read to explore the codebase.**
+The graph is faster, cheaper (fewer tokens), and gives you
+structural context (callers, dependents, test coverage) that file
+scanning cannot.
+
+### Start every workflow with \`ctx_get_minimal_context\`
+
+The first MCP call into ctxloom should always be
+\`ctx_get_minimal_context(task="<what you're about to do>")\`. It
+returns ~150 tokens of orientation plus a task-aware
+\`suggested_first_tool\` you should call next instead of guessing.
+
+### When to use graph tools FIRST
+
+- **Code review**: \`ctx_detect_changes\` + \`ctx_get_review_context\`
+  instead of reading whole files
+- **Understanding impact**: \`ctx_blast_radius\` + \`ctx_get_affected_flows\`
+  instead of manually tracing imports
+- **Refactor planning**: \`ctx_get_call_graph(direction: 'callers')\`
+  + \`ctx_refactor_preview\` before any rename
+- **Architecture questions**: \`ctx_architecture_overview\`,
+  \`ctx_community_list\`, \`ctx_hub_nodes\`
+- **Finding code**: \`ctx_search\` or \`ctx_full_text_search\` instead
+  of \`Grep\`
+
+Fall back to Grep/Glob/Read **only** when the graph doesn't cover
+what you need.
+
+### Follow the \`next_tool_suggestions\` in every response
+
+Every budget-wrapped ctxloom response includes
+\`meta.next_tool_suggestions\` \u2014 author-curated follow-ups with
+\`why\` reasoning and \`estimated_tokens\` per entry. Pick from
+those instead of guessing.
+
+### Token-budget protocol
+
+- Target: \u22648 tool calls per task, \u22642000 total tokens of graph context
+- Pass \`max_response_tokens\` on calls that might return large
+  responses; the budget surface returns skeletons instead of dumping
+- Use \`response_format: 'skeleton'\` when you know you only need
+  signatures, not bodies
+
+### Key tools at a glance
+
+| Tool | Use when |
+|------|----------|
+| \`ctx_get_minimal_context\` | START HERE \u2014 orientation anchor |
+| \`ctx_detect_changes\` | Reviewing code changes; risk-scored |
+| \`ctx_get_review_context\` | Token-efficient review snippets |
+| \`ctx_blast_radius\` | Blast radius of a change |
+| \`ctx_get_affected_flows\` | Execution paths impacted |
+| \`ctx_get_call_graph\` | Callers / callees of a symbol |
+| \`ctx_search\` / \`ctx_full_text_search\` | Find code |
+| \`ctx_architecture_overview\` | High-level codebase map |
+| \`ctx_refactor_preview\` / \`ctx_apply_refactor\` | Plan a rename |
+
+### Hooks keep the graph fresh
+
+\`ctxloom init\` installed a PostToolUse hook on \`Write|Edit\` that
+runs \`ctxloom update --incremental --quiet\` \u2014 so the graph is
+always up to date when you query it. No "did the index update yet?"
+guessing.`;
 var SESSION_START_HEADER = `#!/usr/bin/env bash
 # ctxloom \u2014 agent-harness session-start hook
 # Generated by \`ctxloom init\`. Re-run \`ctxloom init\` to update.
@@ -11640,6 +11717,69 @@ EOF
 fi
 `;
 var SESSION_START_FULL = SESSION_START_HEADER + "\n" + SESSION_START_BODY;
+function plainBody() {
+  return RULES_BLOCK_CONTENT.replace(/^##\s+/gm, "").replace(/^###\s+/gm, "").replace(/^####\s+/gm, "").replace(/\*\*(.*?)\*\*/g, "$1").replace(/`([^`]+)`/g, "$1");
+}
+var CURSOR_HEADER = `# ctxloom \u2014 Cursor agent rules
+# Generated by \`ctxloom init --host=cursor\`. Re-run to update.
+
+`;
+var AIDER_HEADER = `# Project Conventions
+
+Generated by \`ctxloom init --host=aider\`. Re-run to update.
+
+`;
+var COPILOT_HEADER = `# ctxloom \u2014 GitHub Copilot instructions
+
+Generated by \`ctxloom init --host=copilot\`. Re-run to update.
+
+`;
+var WINDSURF_HEADER = `# ctxloom \u2014 Windsurf agent rules
+# Generated by \`ctxloom init --host=windsurf\`. Re-run to update.
+
+`;
+var HOST_ADAPTERS = [
+  // Note: claude / agents / gemini are NOT defined as HostAdapters in
+  // this list — they predate the matrix and live in their own writeRulesBlock
+  // path with HMAC-wrapped Markdown blocks. Future refactor may unify.
+  {
+    id: "cursor",
+    path: ".cursorrules",
+    defaultEnabled: false,
+    render: () => CURSOR_HEADER + plainBody() + "\n",
+    isCanonical(current) {
+      return current === this.render();
+    }
+  },
+  {
+    id: "aider",
+    path: "CONVENTIONS.md",
+    defaultEnabled: false,
+    render: () => AIDER_HEADER + RULES_BLOCK_CONTENT + "\n",
+    isCanonical(current) {
+      return current === this.render();
+    }
+  },
+  {
+    id: "copilot",
+    path: ".github/copilot-instructions.md",
+    defaultEnabled: false,
+    render: () => COPILOT_HEADER + RULES_BLOCK_CONTENT + "\n",
+    isCanonical(current) {
+      return current === this.render();
+    }
+  },
+  {
+    id: "windsurf",
+    path: ".windsurfrules",
+    defaultEnabled: false,
+    render: () => WINDSURF_HEADER + plainBody() + "\n",
+    isCanonical(current) {
+      return current === this.render();
+    }
+  }
+];
+var SUPPORTED_HOST_IDS = HOST_ADAPTERS.map((h) => h.id);
 
 // ../../packages/core/src/install/hmacBlock.ts
 import crypto6 from "crypto";

package/dist/{chunk-7GZVGIQL.js → chunk-J2NLNQ4I.js}

@@ -6,7 +6,8 @@ import {
   generateEmbedding
 } from "./chunk-UVR65QBJ.js";
 import {
-  diskSink
+  diskSink,
+  readEvents
 } from "./chunk-5I6CJITG.js";
 import {
   logger
@@ -4590,29 +4591,110 @@ function registerStatusTool(registry, ctx) {
   );
 }
 
-// packages/core/src/tools/registry.ts
-var ToolRegistry = class {
-  tools = /* @__PURE__ */ new Map();
-  register(name, schema4, handler) {
-    this.tools.set(name, { schema: schema4, handler });
+// packages/core/src/budget/learnedSuggestions.ts
+var DEFAULT_WINDOW_DAYS2 = 14;
+var SESSION_GAP_MS = 9e4;
+var MIN_SAMPLES_PER_PAIR = 3;
+var TOP_K = 3;
+var CACHE_TTL_MS = 60 * 60 * 1e3;
+var _cache = null;
+function __resetLearnedSuggestionsCacheForTests() {
+  _cache = null;
+}
+function clampTokens(n) {
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(0, Math.min(1e5, Math.round(n)));
+}
+function learnSuggestionsFromTelemetry(opts = {}) {
+  const windowDays = opts.windowDays ?? DEFAULT_WINDOW_DAYS2;
+  const sessionGapMs = opts.sessionGapMs ?? SESSION_GAP_MS;
+  const minSamples = opts.minSamples ?? MIN_SAMPLES_PER_PAIR;
+  const allowlist = opts.registeredTools;
+  const events = opts.events ?? safeReadEvents(windowDays);
+  if (events.length === 0) return {};
+  const sorted = events.map((e) => ({ ts: Date.parse(e.ts), tool: e.tool })).filter((e) => Number.isFinite(e.ts) && typeof e.tool === "string" && e.tool.length > 0).sort((a, b) => a.ts - b.ts);
+  const transitions = /* @__PURE__ */ new Map();
+  const tokenSums = /* @__PURE__ */ new Map();
+  let prevTool = null;
+  let prevTs = -Infinity;
+  for (const e of sorted) {
+    if (prevTool && e.tool !== prevTool && e.ts - prevTs <= sessionGapMs) {
+      let row = transitions.get(prevTool);
+      if (!row) {
+        row = /* @__PURE__ */ new Map();
+        transitions.set(prevTool, row);
+      }
+      row.set(e.tool, (row.get(e.tool) ?? 0) + 1);
+    }
+    prevTool = e.tool;
+    prevTs = e.ts;
+  }
+  for (const raw of events) {
+    const tok = raw.original_tokens;
+    if (typeof tok === "number" && Number.isFinite(tok)) {
+      const acc = tokenSums.get(raw.tool) ?? { sum: 0, n: 0 };
+      acc.sum += tok;
+      acc.n += 1;
+      tokenSums.set(raw.tool, acc);
+    }
   }
-  list() {
-    return Array.from(this.tools.values()).map((t) => t.schema);
+  const out = {};
+  for (const [from, row] of transitions) {
+    if (allowlist && !allowlist.has(from)) continue;
+    const candidates = [];
+    for (const [to, count] of row) {
+      if (count < minSamples) continue;
+      if (allowlist && !allowlist.has(to)) continue;
+      const tokenAcc = tokenSums.get(to);
+      const avgTokens = tokenAcc && tokenAcc.n > 0 ? tokenAcc.sum / tokenAcc.n : 0;
+      candidates.push({
+        tool: to,
+        why: `Learned from telemetry: ${count} agents followed ${from} with ${to}.`,
+        estimated_tokens: clampTokens(avgTokens)
+      });
+    }
+    if (candidates.length === 0) continue;
+    candidates.sort((a, b) => {
+      const matchA = a.why.match(/(\d+) agents/);
+      const matchB = b.why.match(/(\d+) agents/);
+      const ca = matchA ? parseInt(matchA[1], 10) : 0;
+      const cb = matchB ? parseInt(matchB[1], 10) : 0;
+      return cb - ca;
+    });
+    out[from] = candidates.slice(0, TOP_K);
   }
-  async dispatch(name, args) {
-    const def = this.tools.get(name);
-    if (!def) throw new Error(`Unknown tool: ${name}`);
-    const projectRoot = args && typeof args === "object" && "project_root" in args ? args.project_root : void 0;
-    logger.debug("tool.dispatch", { tool: name, project_root: projectRoot });
-    return def.handler(args);
+  return out;
+}
+function safeReadEvents(windowDays) {
+  try {
+    const until = /* @__PURE__ */ new Date();
+    const since = new Date(until.getTime() - windowDays * 24 * 60 * 60 * 1e3);
+    return readEvents({ since, until });
+  } catch {
+    return [];
   }
-  has(name) {
-    return this.tools.has(name);
+}
+function getLearnedRules(opts = {}) {
+  if (_cache && _cache.expiresAt > Date.now()) {
+    return filterRulesByAllowlist(_cache.rules, opts.registeredTools);
   }
-};
-
-// packages/core/src/tools/search.ts
-import { z as z3 } from "zod";
+  const unfilteredRules = learnSuggestionsFromTelemetry({
+    ...opts,
+    registeredTools: void 0
+  });
+  _cache = { rules: unfilteredRules, expiresAt: Date.now() + CACHE_TTL_MS };
+  return filterRulesByAllowlist(unfilteredRules, opts.registeredTools);
+}
+function filterRulesByAllowlist(rules, allowlist) {
+  if (!allowlist) return rules;
+  const out = {};
+  for (const [from, suggestions] of Object.entries(rules)) {
+    if (!allowlist.has(from)) continue;
+    const kept = suggestions.filter((s) => allowlist.has(s.tool));
+    if (kept.length > 0) out[from] = kept;
+  }
+  return out;
+}
 
 // packages/core/src/budget/nextToolSuggestions.ts
 var STATIC_RULES = {
@@ -4923,6 +5005,17 @@ function clampEstimate(n) {
   return Math.max(TOKEN_ESTIMATE_MIN, Math.min(TOKEN_ESTIMATE_MAX, Math.round(n)));
 }
 function suggestNext(fromTool, registeredTools) {
+  if (process.env.CTXLOOM_LEARNED_SUGGESTIONS === "1") {
+    const learned = getLearnedRules({ registeredTools })[fromTool];
+    if (learned && learned.length > 0) {
+      return learned.slice(0, 3).map((s) => ({
+        tool: s.tool,
+        args: s.args,
+        why: s.why,
+        estimated_tokens: clampEstimate(s.estimated_tokens)
+      }));
+    }
+  }
   const raw = STATIC_RULES[fromTool] ?? [];
   const filtered = registeredTools ? raw.filter((s) => registeredTools.has(s.tool)) : raw;
   return filtered.slice(0, 3).map((s) => ({
@@ -5141,7 +5234,159 @@ function wrapResponse(result) {
   return JSON.stringify(envelope);
 }
 
+// packages/core/src/budget/taskBudget.ts
+var DEFAULT_MAX_CALLS = 8;
+var DEFAULT_RESET_GAP_MS = 9e4;
+var ENV_VAR = "CTXLOOM_TASK_TOOL_BUDGET";
+function parseEnvBudget() {
+  const raw = process.env[ENV_VAR];
+  if (!raw) return null;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return n;
+}
+var TaskBudgetTracker = class {
+  state = /* @__PURE__ */ new Map();
+  maxCalls;
+  resetGapMs;
+  constructor(opts = {}) {
+    this.maxCalls = opts.maxCalls ?? parseEnvBudget() ?? DEFAULT_MAX_CALLS;
+    this.resetGapMs = opts.resetGapMs ?? DEFAULT_RESET_GAP_MS;
+  }
+  /**
+   * Record a tool call against the budget. Returns the enforcement
+   * decision the dispatch layer should act on.
+   *
+   * @param sessionId — opaque session identifier. Currently a
+   *   single global key ('process'); reserved for future multi-
+   *   session enforcement.
+   * @param now — milliseconds since epoch. Test hook; defaults to
+   *   `Date.now()`.
+   */
+  recordCall(sessionId = "process", now = Date.now()) {
+    if (isBudgetDisabled()) {
+      return {
+        overBudget: false,
+        callCount: 0,
+        maxCalls: this.maxCalls,
+        firstBreach: false
+      };
+    }
+    const existing = this.state.get(sessionId);
+    if (existing && now - existing.lastCallTs > this.resetGapMs) {
+      const fresh = { count: 1, lastCallTs: now, breachEmitted: false };
+      this.state.set(sessionId, fresh);
+      return {
+        overBudget: false,
+        callCount: 1,
+        maxCalls: this.maxCalls,
+        firstBreach: false
+      };
+    }
+    const next = (existing?.count ?? 0) + 1;
+    const wasBreached = existing?.breachEmitted ?? false;
+    const overBudget = next > this.maxCalls;
+    const firstBreach = overBudget && !wasBreached;
+    this.state.set(sessionId, {
+      count: next,
+      lastCallTs: now,
+      breachEmitted: wasBreached || firstBreach
+    });
+    return { overBudget, callCount: next, maxCalls: this.maxCalls, firstBreach };
+  }
+  /**
+   * Test-only: drop all state. Lets tests run in isolation without
+   * depending on order.
+   *
+   * @internal
+   */
+  reset() {
+    this.state.clear();
+  }
+  /**
+   * Test/diagnostic — current call count for the default session.
+   * @internal
+   */
+  __getCount(sessionId = "process") {
+    return this.state.get(sessionId)?.count ?? 0;
+  }
+};
+var _singleton = null;
+function getTaskBudgetTracker() {
+  if (!_singleton) _singleton = new TaskBudgetTracker();
+  return _singleton;
+}
+function __resetTaskBudgetTrackerForTests() {
+  _singleton = null;
+}
+var OVER_BUDGET_ARG_OVERRIDES = Object.freeze({
+  // Budget-surface tools (the 12 source-returning ones).
+  max_response_tokens: 200,
+  response_format: "skeleton",
+  on_budget_exceeded: "skeleton",
+  // Tools with detail_level (hub_nodes, bridge_nodes, etc).
+  detail_level: "minimal"
+});
+function applyOverBudgetOverrides(args) {
+  if (!args || typeof args !== "object") {
+    return { ...OVER_BUDGET_ARG_OVERRIDES };
+  }
+  return { ...args, ...OVER_BUDGET_ARG_OVERRIDES };
+}
+function emitTaskBudgetBreached(toolName, callCount, maxCalls) {
+  emitTelemetry({
+    event: "mcp.task_budget.exceeded",
+    tool: toolName,
+    calls: callCount,
+    budget: maxCalls
+  });
+}
+
+// packages/core/src/tools/registry.ts
+var TASK_BUDGET_EXEMPT = /* @__PURE__ */ new Set([
+  "ctx_get_minimal_context",
+  "ctx_status",
+  "ctx_get_workflow",
+  "ctx_get_rules",
+  "ctx_suggested_questions"
+]);
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  register(name, schema4, handler) {
+    this.tools.set(name, { schema: schema4, handler });
+  }
+  list() {
+    return Array.from(this.tools.values()).map((t) => t.schema);
+  }
+  async dispatch(name, args) {
+    const def = this.tools.get(name);
+    if (!def) throw new Error(`Unknown tool: ${name}`);
+    const projectRoot = args && typeof args === "object" && "project_root" in args ? args.project_root : void 0;
+    logger.debug("tool.dispatch", { tool: name, project_root: projectRoot });
+    let dispatchArgs = args;
+    if (!TASK_BUDGET_EXEMPT.has(name)) {
+      const decision = getTaskBudgetTracker().recordCall();
+      if (decision.overBudget) {
+        dispatchArgs = applyOverBudgetOverrides(args);
+        if (decision.firstBreach) {
+          logger.warn("task tool budget exceeded \u2014 auto-throttling responses to skeleton/minimal", {
+            tool: name,
+            calls: decision.callCount,
+            budget: decision.maxCalls
+          });
+          emitTaskBudgetBreached(name, decision.callCount, decision.maxCalls);
+        }
+      }
+    }
+    return def.handler(dispatchArgs);
+  }
+  has(name) {
+    return this.tools.has(name);
+  }
+};
+
 // packages/core/src/tools/search.ts
+import { z as z3 } from "zod";
 var DEFAULT_MAX_RESPONSE_TOKENS = 4e3;
 var Schema = z3.object({
   query: z3.string().describe("Search query \u2014 natural language or code fragment"),
@@ -8897,7 +9142,7 @@ function computeTopHubs(graph) {
     reason: s.inDeg > s.outDeg ? "fan_in" : s.outDeg > s.inDeg ? "fan_out" : "bridge"
   }));
 }
-var CACHE_TTL_MS = 1e4;
+var CACHE_TTL_MS2 = 1e4;
 var responseCache = /* @__PURE__ */ new Map();
 function cacheKey(projectRoot, task) {
   return `${projectRoot}|${task ?? ""}`;
@@ -8912,7 +9157,7 @@ function cacheGet(key) {
   return e.body;
 }
 function cachePut(key, body) {
-  responseCache.set(key, { expiresAt: Date.now() + CACHE_TTL_MS, body });
+  responseCache.set(key, { expiresAt: Date.now() + CACHE_TTL_MS2, body });
 }
 function sanitizeTask(raw) {
   if (raw == null) return void 0;
@@ -9960,7 +10205,7 @@ var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
 function getTelemetryLevel() {
   return TELEMETRY_LEVEL;
 }
-var CTXLOOM_VERSION = "1.4.0".length > 0 ? "1.4.0" : "dev";
+var CTXLOOM_VERSION = "1.5.0".length > 0 ? "1.5.0" : "dev";
 var POSTHOG_HOST = "https://eu.i.posthog.com";
 var POSTHOG_KEY = process.env["POSTHOG_API_KEY"] ?? (true ? "phc_CiDkmFLcZ2K6uCpcoSUQLmFrnnUvsyXGhSxopX5TVKE6" : "");
 var SENTRY_DSN = process.env["SENTRY_DSN"] ?? (true ? "https://81c94a0f04a8e242dee493ac1e17f733@o4508531702497280.ingest.de.sentry.io/4511256875368528" : "");
@@ -10711,6 +10956,72 @@ var CTXLOOM_HOOK_ENTRIES = {
     ]
   }
 };
+function plainBody() {
+  return RULES_BLOCK_CONTENT.replace(/^##\s+/gm, "").replace(/^###\s+/gm, "").replace(/^####\s+/gm, "").replace(/\*\*(.*?)\*\*/g, "$1").replace(/`([^`]+)`/g, "$1");
+}
+var CURSOR_HEADER = `# ctxloom \u2014 Cursor agent rules
+# Generated by \`ctxloom init --host=cursor\`. Re-run to update.
+
+`;
+var AIDER_HEADER = `# Project Conventions
+
+Generated by \`ctxloom init --host=aider\`. Re-run to update.
+
+`;
+var COPILOT_HEADER = `# ctxloom \u2014 GitHub Copilot instructions
+
+Generated by \`ctxloom init --host=copilot\`. Re-run to update.
+
+`;
+var WINDSURF_HEADER = `# ctxloom \u2014 Windsurf agent rules
+# Generated by \`ctxloom init --host=windsurf\`. Re-run to update.
+
+`;
+var HOST_ADAPTERS = [
+  // Note: claude / agents / gemini are NOT defined as HostAdapters in
+  // this list — they predate the matrix and live in their own writeRulesBlock
+  // path with HMAC-wrapped Markdown blocks. Future refactor may unify.
+  {
+    id: "cursor",
+    path: ".cursorrules",
+    defaultEnabled: false,
+    render: () => CURSOR_HEADER + plainBody() + "\n",
+    isCanonical(current) {
+      return current === this.render();
+    }
+  },
+  {
+    id: "aider",
+    path: "CONVENTIONS.md",
+    defaultEnabled: false,
+    render: () => AIDER_HEADER + RULES_BLOCK_CONTENT + "\n",
+    isCanonical(current) {
+      return current === this.render();
+    }
+  },
+  {
+    id: "copilot",
+    path: ".github/copilot-instructions.md",
+    defaultEnabled: false,
+    render: () => COPILOT_HEADER + RULES_BLOCK_CONTENT + "\n",
+    isCanonical(current) {
+      return current === this.render();
+    }
+  },
+  {
+    id: "windsurf",
+    path: ".windsurfrules",
+    defaultEnabled: false,
+    render: () => WINDSURF_HEADER + plainBody() + "\n",
+    isCanonical(current) {
+      return current === this.render();
+    }
+  }
+];
+function getHostAdapter(id) {
+  return HOST_ADAPTERS.find((h) => h.id === id);
+}
+var SUPPORTED_HOST_IDS = HOST_ADAPTERS.map((h) => h.id);
 
 // packages/core/src/install/hmacBlock.ts
 import crypto6 from "crypto";
@@ -11159,6 +11470,9 @@ function installHarness(opts = {}) {
   const hooksJson = writeHooksJson(projectRoot, { dryRun, warnings });
   const sessionStartSh = writeSessionStartScript(projectRoot, { dryRun });
   const skills = CTXLOOM_SKILLS.map((s) => writeSkill(projectRoot, s, { dryRun }));
+  const extraHosts = resolveExtraHosts(opts.extraHosts ?? [], warnings).map(
+    (adapter) => Object.assign(writeHostAdapter(projectRoot, adapter, { dryRun }), { hostId: adapter.id })
+  );
   return {
     projectRoot,
     claudeMd,
@@ -11167,9 +11481,29 @@ function installHarness(opts = {}) {
     hooksJson,
     sessionStartSh,
     skills,
+    extraHosts,
     warnings
   };
 }
+function resolveExtraHosts(ids, warnings) {
+  const requested = /* @__PURE__ */ new Set();
+  for (const raw of ids) {
+    const id = raw.trim().toLowerCase();
+    if (id === "") continue;
+    if (id === "all") {
+      for (const a of HOST_ADAPTERS) requested.add(a.id);
+      continue;
+    }
+    if (!getHostAdapter(id)) {
+      warnings.push(
+        `Unknown --host id "${id}" \u2014 ignored. Supported: ${HOST_ADAPTERS.map((a) => a.id).join(", ")}, or "all".`
+      );
+      continue;
+    }
+    requested.add(id);
+  }
+  return HOST_ADAPTERS.filter((a) => requested.has(a.id));
+}
 function safeJoin(root, name) {
   const target = path36.resolve(root, name);
   const rootResolved = path36.resolve(root);
@@ -11262,6 +11596,30 @@ function isCtxloomEntry(entry, expectedMatcher) {
     return cmd.includes("ctxloom") || cmd.includes(".claude/hooks/session-start.sh");
   });
 }
+function writeHostAdapter(projectRoot, adapter, opts) {
+  const filePath = safeJoin(projectRoot, adapter.path);
+  const dir = path36.dirname(filePath);
+  const existed = fs28.existsSync(filePath);
+  const rendered = adapter.render();
+  let alreadyCorrect = false;
+  if (existed) {
+    const current = fs28.readFileSync(filePath, "utf-8");
+    if (adapter.isCanonical(current)) {
+      alreadyCorrect = true;
+    }
+  }
+  if (!opts.dryRun && !alreadyCorrect) {
+    fs28.mkdirSync(dir, { recursive: true });
+    fs28.writeFileSync(filePath, rendered, "utf-8");
+  }
+  return {
+    path: filePath,
+    created: !existed,
+    updated: existed && !alreadyCorrect,
+    alreadyCorrect,
+    dryRun: opts.dryRun
+  };
+}
 function writeSkill(projectRoot, skill, opts) {
   const dir = safeJoin(projectRoot, `.claude/skills/${skill.name}`);
   const filePath = safeJoin(projectRoot, skillFilePath(skill.name));
@@ -11347,6 +11705,15 @@ export {
   loadFileRiskHistory,
   Skeletonizer,
   renderStatusXml,
+  __resetLearnedSuggestionsCacheForTests,
+  learnSuggestionsFromTelemetry,
+  getLearnedRules,
+  TaskBudgetTracker,
+  getTaskBudgetTracker,
+  __resetTaskBudgetTrackerForTests,
+  OVER_BUDGET_ARG_OVERRIDES,
+  applyOverBudgetOverrides,
+  emitTaskBudgetBreached,
   ToolRegistry,
   detectChanges,
   getImpactRadius,
@@ -11419,6 +11786,9 @@ export {
   RULES_BLOCK_CONTENT,
   SESSION_START_FULL,
   CTXLOOM_HOOK_ENTRIES,
+  HOST_ADAPTERS,
+  getHostAdapter,
+  SUPPORTED_HOST_IDS,
   DEFAULT_HMAC_KEY,
   resolveHmacKey,
   computeBlockHmac,
@@ -11430,4 +11800,4 @@ export {
   skillFilePath,
   installHarness
 };
-//# sourceMappingURL=chunk-7GZVGIQL.js.map
+//# sourceMappingURL=chunk-J2NLNQ4I.js.map

package/dist/index.js

@@ -49,7 +49,7 @@ import {
   validateDefaultRoot,
   wrapWithIndexingEnvelope,
   writeCODEOWNERS
-} from "./chunk-7GZVGIQL.js";
+} from "./chunk-J2NLNQ4I.js";
 import {
   VectorStore
 } from "./chunk-DVI2RWJR.js";
@@ -1019,7 +1019,7 @@ try {
 } catch {
 }
 var args = process.argv.slice(2);
-var ctxloomVersion = "1.4.0".length > 0 ? "1.4.0" : "dev";
+var ctxloomVersion = "1.5.0".length > 0 ? "1.5.0" : "dev";
 if (args.includes("--version") || args.includes("-v")) {
   process.stdout.write(`ctxloom ${ctxloomVersion}
 `);
@@ -1092,7 +1092,7 @@ async function checkLicense() {
   if (command !== void 0 && LICENSE_GATE_BYPASS_COMMANDS.has(command)) return;
   const ciKey = process.env["CTXLOOM_LICENSE_KEY"];
   if (ciKey) {
-    const { ApiClient } = await import("./src-CH2OSHKF.js");
+    const { ApiClient } = await import("./src-PVBWVQMM.js");
     const client = new ApiClient(process.env["CTXLOOM_API_BASE"]);
     try {
       const result = await client.validate(ciKey, "ci-ephemeral");
@@ -1447,6 +1447,15 @@ async function main() {
       const skipHarness = process.argv.includes("--skip-harness");
       const dryRun = process.argv.includes("--dry-run");
       const force = process.argv.includes("--force");
+      const extraHosts = [];
+      for (let i = 0; i < process.argv.length; i++) {
+        const arg = process.argv[i];
+        if (arg.startsWith("--host=")) {
+          extraHosts.push(...arg.slice("--host=".length).split(",").map((s) => s.trim()));
+        } else if (arg === "--host" && i + 1 < process.argv.length) {
+          extraHosts.push(...process.argv[i + 1].split(",").map((s) => s.trim()));
+        }
+      }
       try {
         const result = runInit(initRoot);
         const mcpLabel = result.mcpJson.created ? `${style.bold("Created")} ${result.mcpJson.path}` : result.mcpJson.merged ? `${style.bold("Merged ctxloom entry into")} ${result.mcpJson.path}` : `${style.dim("Already up to date:")} ${result.mcpJson.path}`;
@@ -1461,15 +1470,16 @@ async function main() {
         }
         if (!skipHarness) {
           process.stdout.write("\n");
-          const { installHarness } = await import("./src-CH2OSHKF.js");
-          const h = installHarness({ cwd: initRoot, dryRun, force });
+          const { installHarness } = await import("./src-PVBWVQMM.js");
+          const h = installHarness({ cwd: initRoot, dryRun, force, extraHosts });
           const harnessFiles = [
             h.claudeMd,
             h.agentsMd,
             h.geminiMd,
             h.hooksJson,
             h.sessionStartSh,
-            ...h.skills
+            ...h.skills,
+            ...h.extraHosts
           ];
           for (const fr of harnessFiles) {
             const rel = path4.relative(initRoot, fr.path);
@@ -1523,7 +1533,7 @@ async function main() {
         process.exit(1);
       }
       if (alias !== void 0) {
-        const { validateAlias } = await import("./src-CH2OSHKF.js");
+        const { validateAlias } = await import("./src-PVBWVQMM.js");
         const v = validateAlias(alias);
         if (!v.ok) {
           console.error(`[ctxloom] Invalid alias: ${v.reason}`);
@@ -1787,7 +1797,7 @@ Suggested reviewers for ${files.length} file(s):`);
         process.stderr.write("[ctxloom] --limit must be a non-negative integer (0 for unlimited)\n");
         process.exit(2);
       }
-      const { loadRulesConfig, RulesChecker, formatText, formatJson, RulesConfigError } = await import("./src-CH2OSHKF.js");
+      const { loadRulesConfig, RulesChecker, formatText, formatJson, RulesConfigError } = await import("./src-PVBWVQMM.js");
       let config;
       try {
         config = await loadRulesConfig(root);
@@ -1811,7 +1821,7 @@ Suggested reviewers for ${files.length} file(s):`);
       }
       let graph;
       if (useSnapshot) {
-        const { DependencyGraph: DG } = await import("./src-CH2OSHKF.js");
+        const { DependencyGraph: DG } = await import("./src-PVBWVQMM.js");
         graph = new DG();
         const loaded = await graph.loadSnapshotOnly(root);
         if (!loaded) {
@@ -1820,7 +1830,7 @@ Suggested reviewers for ${files.length} file(s):`);
         }
       } else {
         process.stderr.write("[ctxloom] Building dependency graph...\n");
-        const { ASTParser: ASTParser2, DependencyGraph: DependencyGraph2 } = await import("./src-CH2OSHKF.js");
+        const { ASTParser: ASTParser2, DependencyGraph: DependencyGraph2 } = await import("./src-PVBWVQMM.js");
         let parser;
         try {
           parser = new ASTParser2();

package/dist/{src-CH2OSHKF.js → src-PVBWVQMM.js}

@@ -24,11 +24,13 @@ import {
   GoModuleResolver,
   GrammarLoader,
   GraphExporter,
+  HOST_ADAPTERS,
   InvalidKeyError,
   LicenseRequiredError,
   LicenseRevokedError,
   LicenseStore,
   NetworkError,
+  OVER_BUDGET_ARG_OVERRIDES,
   OwnershipIndex,
   PathValidator,
   ProjectStateManager,
@@ -42,14 +44,19 @@ import {
   SCORE_FLOOR,
   SESSION_START_FULL,
   SILO_BUS_FACTOR,
+  SUPPORTED_HOST_IDS,
   SeatLimitError,
   Skeletonizer,
+  TaskBudgetTracker,
   ToolRegistry,
   TrialUnavailableError,
   TsConfigPathsResolver,
   WikiGenerator,
+  __resetLearnedSuggestionsCacheForTests,
+  __resetTaskBudgetTrackerForTests,
   activateLicense,
   aliasNotFoundError,
+  applyOverBudgetOverrides,
   assignLabelsByPercentile,
   buildBlastRadiusXml,
   buildCodeownersBlock,
@@ -62,6 +69,7 @@ import {
   deactivateLicense,
   detectChanges,
   disposeProjectState,
+  emitTaskBudgetBreached,
   ensureVectorsInitialized,
   extractBlock,
   extractImports,
@@ -73,14 +81,18 @@ import {
   formatJson,
   formatText,
   generateCODEOWNERS,
+  getHostAdapter,
   getImpactRadius,
+  getLearnedRules,
   getLicenseInfo,
   getOrCreateDistinctId,
+  getTaskBudgetTracker,
   getTelemetryLevel,
   hashProjectRoot,
   installHarness,
   isActive,
   isSiloed,
+  learnSuggestionsFromTelemetry,
   listNamedSnapshots,
   loadFileRiskHistory,
   loadReviewConfig,
@@ -117,7 +129,7 @@ import {
   wrapBlock,
   wrapWithIndexingEnvelope,
   writeCODEOWNERS
-} from "./chunk-7GZVGIQL.js";
+} from "./chunk-J2NLNQ4I.js";
 import {
   VectorStore
 } from "./chunk-DVI2RWJR.js";
@@ -158,11 +170,13 @@ export {
   GoModuleResolver,
   GrammarLoader,
   GraphExporter,
+  HOST_ADAPTERS,
   InvalidKeyError,
   LicenseRequiredError,
   LicenseRevokedError,
   LicenseStore,
   NetworkError,
+  OVER_BUDGET_ARG_OVERRIDES,
   OwnershipIndex,
   PathValidator,
   ProjectStateManager,
@@ -176,15 +190,20 @@ export {
   SCORE_FLOOR,
   SESSION_START_FULL,
   SILO_BUS_FACTOR,
+  SUPPORTED_HOST_IDS,
   SeatLimitError,
   Skeletonizer,
+  TaskBudgetTracker,
   ToolRegistry,
   TrialUnavailableError,
   TsConfigPathsResolver,
   VectorStore,
   WikiGenerator,
+  __resetLearnedSuggestionsCacheForTests,
+  __resetTaskBudgetTrackerForTests,
   activateLicense,
   aliasNotFoundError,
+  applyOverBudgetOverrides,
   assignLabelsByPercentile,
   buildBlastRadiusXml,
   buildCodeownersBlock,
@@ -198,6 +217,7 @@ export {
   deactivateLicense,
   detectChanges,
   disposeProjectState,
+  emitTaskBudgetBreached,
   ensureVectorsInitialized,
   extractBlock,
   extractImports,
@@ -210,15 +230,19 @@ export {
   formatText,
   generateCODEOWNERS,
   generateEmbedding,
+  getHostAdapter,
   getImpactRadius,
+  getLearnedRules,
   getLicenseInfo,
   getOrCreateDistinctId,
+  getTaskBudgetTracker,
   getTelemetryLevel,
   hashProjectRoot,
   indexDirectory,
   installHarness,
   isActive,
   isSiloed,
+  learnSuggestionsFromTelemetry,
   listNamedSnapshots,
   loadFileRiskHistory,
   loadReviewConfig,
@@ -257,4 +281,4 @@ export {
   wrapWithIndexingEnvelope,
   writeCODEOWNERS
 };
-//# sourceMappingURL=src-CH2OSHKF.js.map
+//# sourceMappingURL=src-PVBWVQMM.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctxloom-pro",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "ctxloom — The Universal Code Context Engine. A local-first MCP server providing intelligent code context via hybrid Vector + AST + Graph search with Skeletonization (92% token reduction).",
   "type": "module",
   "main": "dist/index.js",