ctxloom-pro 1.2.7 → 1.3.0

package/README.md

@@ -502,6 +502,83 @@ Pass `--no-git` to disable the overlay entirely. Tools degrade gracefully — th
 
 ---
 
+## Response Budgets (v1.2.7+)
+
+Twelve source-returning tools accept a server-enforced **token budget**. When a response would exceed the budget, the server auto-substitutes a lighter form (Skeletonizer signature view, summary-only XML, or paths-without-snippets) instead of dumping 50KB of source into your context window.
+
+### Opting in
+
+Pass any of these three optional fields to any of the 12 supported tools:
+
+```json
+{
+  "max_response_tokens": 4000,
+  "on_budget_exceeded": "skeleton",
+  "response_format": "auto"
+}
+```
+
+| Field | Values | Default |
+|---|---|---|
+| `max_response_tokens` | positive integer | per-tool (see below) |
+| `on_budget_exceeded` | `"skeleton"` \| `"truncate"` \| `"error"` | `"skeleton"` |
+| `response_format` | `"full"` \| `"skeleton"` \| `"auto"` | `"auto"` |
+
+**Back-compat:** when none of these fields are passed, the tool returns its raw response unchanged. Existing callers see zero behavior change.
+
+### Response envelope
+
+When you opt in, the response is wrapped in a JSON envelope:
+
+```json
+{
+  "data": "<the actual tool output — XML, text, or whatever the tool returns>",
+  "meta": {
+    "format": "full" | "skeleton" | "truncated",
+    "original_tokens_est": 8400,
+    "returned_tokens_est": 1600,
+    "fallback_reason": null | "budget_exceeded" | "minified_input" | "size_cap" | "skeleton_failed"
+  }
+}
+```
+
+### Supported tools + default budgets
+
+Defaults activate only when you opt in (any of the 3 fields above) without specifying `max_response_tokens` explicitly.
+
+| Tool | Default | Skeleton fallback |
+|---|---:|---|
+| `ctx_get_file` | 8000 | Skeletonizer view of the file (~90% reduction on TS) |
+| `ctx_get_context_packet` | 6000 | Re-render with the primary file skeletonized |
+| `ctx_get_definition` | 2000 | none — truncate-only (already structural) |
+| `ctx_git_diff_review` | 8000 | Drop `<skeleton>` blocks + omit transitive importers |
+| `ctx_search` | 4000 | Drop content snippets (paths + scores only) |
+| `ctx_full_text_search` | 4000 | Drop match snippets (paths + match counts only) |
+| `ctx_wiki_generate` | 12000 | Downgrade to `detail_level=minimal` |
+| `ctx_find_large_functions` | 2000 | none — truncate-only |
+| `ctx_apply_refactor` | 2000 | none — truncate-only |
+| `ctx_refactor_preview` | 4000 | Drop per-change before/after, keep file summary |
+| `ctx_cross_repo_search` | 4000 | Drop content snippets |
+| `ctx_execution_flow` | 4000 | none — truncate-only |
+
+Defaults are **provisional** (derived from the issue's initial table); a future release will re-derive them from real per-tool p75 telemetry once enough usage data accumulates.
+
+### Token estimator
+
+Default = `chars / 4` — within ±10% of GPT/Claude tokenizers on code with zero tokenization cost. Pluggable per-tool via the `estimator` option on `BudgetOptions` for callers that need accuracy-critical estimation (e.g. tiktoken).
+
+### Kill switch
+
+Set `CTXLOOM_DISABLE_BUDGET=1` in the environment to silently ignore every `max_response_tokens` arg server-wide. Tools behave exactly as in pre-v1.2.7. Documented escape hatch for the soak period.
+
+### Telemetry
+
+Set `CTXLOOM_TELEMETRY_LEVEL=full` to emit structured `mcp.budget.exceeded` and `mcp.fallback.used` events to stderr. Useful for tuning defaults against your own usage patterns.
+
+> **Note:** `CTXLOOM_TELEMETRY_LEVEL` is also consumed by the license / PostHog telemetry layer (see [Telemetry](#telemetry) below) which only recognizes `all` / `error` / `off`. `full` is a separate, **additive** level — it enables budget-event emission *without narrowing* PostHog scope. To narrow PostHog telemetry, set the variable to `error` or `off`; those values disable budget events as a side effect.
+
+---
+
 ## CLI Commands
 
 ```

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

@@ -11422,7 +11422,7 @@ function resolveTelemetryLevel() {
 }
 var TELEMETRY_LEVEL = resolveTelemetryLevel();
 var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
-var CTXLOOM_VERSION = "1.2.7".length > 0 ? "1.2.7" : "dev";
+var CTXLOOM_VERSION = "1.3.0".length > 0 ? "1.3.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" : "");

package/dist/{chunk-RY3JAC2Q.js → chunk-Q2KTZNNU.js}

@@ -9342,7 +9342,7 @@ var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
 function getTelemetryLevel() {
   return TELEMETRY_LEVEL;
 }
-var CTXLOOM_VERSION = "1.2.7".length > 0 ? "1.2.7" : "dev";
+var CTXLOOM_VERSION = "1.3.0".length > 0 ? "1.3.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" : "");
@@ -10072,4 +10072,4 @@ export {
   FirstTouchTracker,
   EmittedOnceTracker
 };
-//# sourceMappingURL=chunk-RY3JAC2Q.js.map
+//# sourceMappingURL=chunk-Q2KTZNNU.js.map

package/dist/index.js

@@ -49,7 +49,7 @@ import {
   validateDefaultRoot,
   wrapWithIndexingEnvelope,
   writeCODEOWNERS
-} from "./chunk-RY3JAC2Q.js";
+} from "./chunk-Q2KTZNNU.js";
 import {
   VectorStore
 } from "./chunk-DVI2RWJR.js";
@@ -1018,7 +1018,7 @@ try {
 } catch {
 }
 var args = process.argv.slice(2);
-var ctxloomVersion = "1.2.7".length > 0 ? "1.2.7" : "dev";
+var ctxloomVersion = "1.3.0".length > 0 ? "1.3.0" : "dev";
 if (args.includes("--version") || args.includes("-v")) {
   process.stdout.write(`ctxloom ${ctxloomVersion}
 `);
@@ -1091,7 +1091,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-3ZB6BHFW.js");
+    const { ApiClient } = await import("./src-HNXOOOWF.js");
     const client = new ApiClient(process.env["CTXLOOM_API_BASE"]);
     try {
       const result = await client.validate(ciKey, "ci-ephemeral");
@@ -1496,7 +1496,7 @@ async function main() {
         process.exit(1);
       }
       if (alias !== void 0) {
-        const { validateAlias } = await import("./src-3ZB6BHFW.js");
+        const { validateAlias } = await import("./src-HNXOOOWF.js");
         const v = validateAlias(alias);
         if (!v.ok) {
           console.error(`[ctxloom] Invalid alias: ${v.reason}`);
@@ -1743,7 +1743,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-3ZB6BHFW.js");
+      const { loadRulesConfig, RulesChecker, formatText, formatJson, RulesConfigError } = await import("./src-HNXOOOWF.js");
       let config;
       try {
         config = await loadRulesConfig(root);
@@ -1767,7 +1767,7 @@ Suggested reviewers for ${files.length} file(s):`);
       }
       let graph;
       if (useSnapshot) {
-        const { DependencyGraph: DG } = await import("./src-3ZB6BHFW.js");
+        const { DependencyGraph: DG } = await import("./src-HNXOOOWF.js");
         graph = new DG();
         const loaded = await graph.loadSnapshotOnly(root);
         if (!loaded) {
@@ -1776,7 +1776,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-3ZB6BHFW.js");
+        const { ASTParser: ASTParser2, DependencyGraph: DependencyGraph2 } = await import("./src-HNXOOOWF.js");
         let parser;
         try {
           parser = new ASTParser2();

package/dist/{src-3ZB6BHFW.js → src-HNXOOOWF.js}

@@ -103,7 +103,7 @@ import {
   validateDefaultRoot,
   wrapWithIndexingEnvelope,
   writeCODEOWNERS
-} from "./chunk-RY3JAC2Q.js";
+} from "./chunk-Q2KTZNNU.js";
 import {
   VectorStore
 } from "./chunk-DVI2RWJR.js";
@@ -228,4 +228,4 @@ export {
   wrapWithIndexingEnvelope,
   writeCODEOWNERS
 };
-//# sourceMappingURL=src-3ZB6BHFW.js.map
+//# sourceMappingURL=src-HNXOOOWF.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctxloom-pro",
-  "version": "1.2.7",
+  "version": "1.3.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",