ctxloom-pro 1.2.6 → 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

@@ -8290,16 +8290,29 @@ init_logger();
 
 // ../../packages/core/src/tools/search.ts
 init_embedder();
+
+// ../../packages/core/src/budget/budget.ts
+init_logger();
+
+// ../../packages/core/src/tools/search.ts
 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"),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when budget surface is opted into). Over-budget rebuilds the result list without the content snippets (paths + scores only)."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops snippets; 'truncate' slices the raw XML; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the path-and-score-only view; 'full'/'auto' lets the budget decide.")
 });
 
 // ../../packages/core/src/tools/file.ts
 var Schema2 = external_exports.object({
   path: external_exports.string().describe("Relative path to the file"),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface (all optional; back-compat preserved) ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget in tokens. Falls back to a skeleton when exceeded. Default: 8000 (when budget surface is opted into)."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when the response would exceed max_response_tokens. 'skeleton' (default) substitutes a Skeletonizer signature view; 'truncate' slices the raw text; 'error' throws a structured error with token counts so the caller can re-ask."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces a Skeletonizer view regardless of budget; 'full'/'auto' lets the budget decide.")
 });
 
 // ../../packages/core/src/tools/context-packet.ts
@@ -8307,7 +8320,11 @@ import path16 from "path";
 var Schema3 = external_exports.object({
   target_file: external_exports.string().describe("Relative path to the primary file"),
   mode: external_exports.enum(["edit", "read"]).optional().default("edit").describe("Context mode"),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 6000 (when budget surface is opted into). Over-budget rebuilds the packet with the primary file replaced by its skeleton."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) re-renders the packet with the primary file skeletonized; 'truncate' slices the raw envelope; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the skeletonized-primary packet; 'full'/'auto' lets the budget decide.")
 });
 
 // ../../packages/core/src/tools/findCallers.ts
@@ -8325,7 +8342,11 @@ var Schema4 = external_exports.object({
 // ../../packages/core/src/tools/definition.ts
 var Schema5 = external_exports.object({
   symbol: external_exports.string().describe("Symbol name to look up"),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface (all optional; back-compat preserved) ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget in tokens. Default: 2000 (when budget surface is opted into). No skeleton fallback for this tool \u2014 the response is structural metadata; over-budget falls back to truncation."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton'/'truncate' both slice the XML (no file context to skeletonize from); 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'full'/'auto' default. 'skeleton' is accepted for consistency but produces the same output as 'full' here \u2014 the response is already a compact symbol list.")
 });
 
 // ../../packages/core/src/tools/rules.ts
@@ -8445,7 +8466,11 @@ var Schema15 = external_exports.object({
   detail_level: external_exports.enum(["standard", "minimal"]).default("standard").describe(
     '"standard" (default) lists each written page with size. "minimal" returns counts only.'
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 12000 (when opted in). Over-budget re-renders at detail_level=minimal (counts only) \u2014 the wiki files themselves are unaffected."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) downgrades to minimal output; 'truncate' slices; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces minimal output regardless of budget; 'full'/'auto' lets the budget decide.")
 });
 
 // ../../packages/core/src/tools/graph-export.ts
@@ -8473,7 +8498,11 @@ var Schema17 = external_exports.object({
   max_diff_lines: external_exports.number().min(10).max(2e3).optional().default(300).describe(
     "Max diff lines to include per file (default: 300)"
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 8000 (when opted in). Over-budget re-renders without <skeleton> blocks and without the transitive_importers section \u2014 keeps diffs, direct importers, and call sites."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops skeletons + transitive importers; 'truncate' slices; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the lighter view; 'full'/'auto' lets the budget decide.")
 });
 
 // ../../packages/core/src/tools/refactor-preview.ts
@@ -8485,7 +8514,11 @@ var Schema18 = external_exports.object({
   max_files: external_exports.number().min(1).max(200).optional().default(50).describe(
     "Maximum number of files to scan for occurrences (default: 50)"
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when opted in). Over-budget drops the per-change before/after lines; keeps the file+occurrence summary so callers can decide which files to drill into."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops change details; 'truncate' slices; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the summary-only view; 'full'/'auto' lets the budget decide.")
 });
 
 // ../../packages/core/src/tools/execution-flow.ts
@@ -8498,7 +8531,11 @@ var Schema19 = external_exports.object({
   max_nodes: external_exports.number().min(1).max(200).optional().default(50).describe(
     "Max total steps to include in output (default: 50)"
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when opted in). No skeleton fallback \u2014 response is already a bounded step list; over-budget falls through to truncation."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton'/'truncate' both slice; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'full'/'auto' default; 'skeleton' same output.")
 });
 
 // ../../packages/core/src/tools/cross-repo-search.ts
@@ -8515,7 +8552,11 @@ var Schema20 = external_exports.object({
   repos: external_exports.array(external_exports.string()).optional().describe(
     "Specific repo root paths to search. Omit to search all registered repos."
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when opted in). Over-budget drops content snippets (repo + path + score only)."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops content snippets; 'truncate' slices; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the path-and-score-only view; 'full'/'auto' lets the budget decide.")
 });
 
 // ../../packages/core/src/tools/apply-refactor.ts
@@ -8530,7 +8571,11 @@ var Schema21 = external_exports.object({
   max_files: external_exports.number().min(1).max(200).optional().default(50).describe(
     "Maximum candidate files to process (default: 50)"
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 2000 (when opted in). No skeleton fallback \u2014 response is already compact; over-budget falls through to truncation."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton'/'truncate' both slice the XML; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'full'/'auto' default; 'skeleton' produces the same output.")
 });
 
 // ../../packages/core/src/tools/detect-changes.ts
@@ -8557,7 +8602,11 @@ var Schema23 = external_exports.object({
   case_sensitive: external_exports.boolean().optional().default(false),
   limit: external_exports.number().min(1).max(100).optional().default(20),
   context_lines: external_exports.number().min(0).max(5).optional().default(1),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 4000 (when budget surface is opted into). Over-budget rebuilds the result list without match snippets (paths + match counts only)."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton' (default) drops snippets; 'truncate' slices the raw XML; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'skeleton' forces the path-and-count-only view; 'full'/'auto' lets the budget decide.")
 });
 
 // ../../packages/core/src/tools/suggested-questions.ts
@@ -8610,7 +8659,11 @@ var schema3 = external_exports.object({
   limit: external_exports.number().int().min(1).max(200).default(30).describe(
     "Maximum results to return (default: 30)."
   ),
-  project_root: ProjectRootField
+  project_root: ProjectRootField,
+  // ─── Phase B2 budget surface ──
+  max_response_tokens: external_exports.number().int().positive().optional().describe("Soft response budget. Default: 2000 (when opted in). No skeleton fallback \u2014 response is already structural; over-budget falls through to truncation."),
+  on_budget_exceeded: external_exports.enum(["skeleton", "truncate", "error"]).optional().describe("Behavior when over budget. 'skeleton'/'truncate' both slice the XML; 'error' throws."),
+  response_format: external_exports.enum(["full", "skeleton", "auto"]).optional().describe("'full'/'auto' default; 'skeleton' produces the same output (response is already compact).")
 });
 
 // ../../packages/core/src/tools/git-coupling.ts
@@ -11369,7 +11422,7 @@ function resolveTelemetryLevel() {
 }
 var TELEMETRY_LEVEL = resolveTelemetryLevel();
 var TELEMETRY_DISABLED = TELEMETRY_LEVEL === "off";
-var CTXLOOM_VERSION = "1.2.6".length > 0 ? "1.2.6" : "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" : "");