@launchsecure/launch-kit 0.0.2 → 0.0.3

package/dist/server/cli.js

@@ -7444,7 +7444,7 @@ var TOOLS = [
   },
   {
     name: "read_graph",
-    description: 'Query the structural project graph \u2014 a smart Glob replacement that locates files by type/module/name and returns structural metadata (imports, renders, routes, relations). \n\nUSE THIS FOR: "where is X", "what files are in module Y", "what pages exist under /admin", "what components does Z render", "what tables relate to User", "list all hooks in auth module". \n\nDO NOT USE FOR: finding text/code content (use Grep), reading actual source code (use Read), understanding behavior/logic/patterns (graph has no code semantics \u2014 only names and edges). \n\nQUERY PARAMS (at least one required for node data \u2014 unfiltered calls return summary only to stay in context):\n- search: substring match on node id, name, or route\n- type: filter by node type (ui layer: page, layout, component, ui, hook, context, config, util; api layer: endpoint; db layer: table, enum)\n- module: filter by module (ui layer only: auth, admin, project, org, settings, integrations, shared-ui, layout, root)\n- node_id: return this node + its neighborhood (incoming+outgoing edges within `hops`)\n- hops: neighborhood radius when node_id is set (default 1)\n- minimal: return only id/type/name/module/route per node (skip heavy fields like columns, exports)\n\nBATCH MODE: pass `queries` (array of query objects) to run multiple independent queries in a single call. Each query object uses the same params (layer/search/type/module/node_id/hops/minimal). Returns { batch: true, count, results: [{index, query, result}, ...] }. Use this when you need multiple graph views up-front (e.g. scoping a feature across ui+api+db layers) to save round-trips. When batch mode is used, top-level params are ignored.\n\nReturns: filtered nodes + edges between them. If no filter given, returns per-layer counts and type breakdown only.',
+    description: 'Query the structural project graph \u2014 a smart Glob replacement that locates files by type/module/name and returns structural metadata (imports, renders, routes, relations). \n\nUSE THIS FOR: "where is X", "what files are in module Y", "what pages exist under /admin", "what components does Z render", "what tables relate to User", "list all hooks in auth module". \n\nDO NOT USE FOR: finding text/code content (use Grep), reading actual source code (use Read), understanding behavior/logic/patterns (graph has no code semantics \u2014 only names and edges). \n\nQUERY PARAMS (at least one required for node data \u2014 unfiltered calls return summary only to stay in context):\n- search: substring match on node id, name, or route\n- type: filter by node type (ui layer: page, layout, component, ui, hook, context, config, util; api layer: endpoint; db layer: table, enum)\n- module: filter by module (ui layer only: auth, admin, project, org, settings, integrations, shared-ui, layout, root)\n- node_id: return this node + its neighborhood (incoming+outgoing edges within `hops`)\n- hops: neighborhood radius when node_id is set (default 1)\n- minimal: return only id/type/name/module/route per node (skip heavy fields like columns, exports)\n- include_edges: return the actual edge list. Default: TRUE for neighborhood queries (node_id), FALSE for filter queries (search/type/module). Filter responses always include `edge_count`; only pass include_edges:true when you actually need to inspect individual edges (e.g. "which components render X"). This default cuts typical filter responses in half.\n\nBATCH MODE: pass `queries` (array of query objects) to run multiple independent queries in a single call. Each query object uses the same params (layer/search/type/module/node_id/hops/minimal). Returns { batch: true, count, results: [{index, query, result}, ...] }. Use this when you need multiple graph views up-front (e.g. scoping a feature across ui+api+db layers) to save round-trips. When batch mode is used, top-level params are ignored.\n\nReturns: filtered nodes + edges between them. If no filter given, returns per-layer counts and type breakdown only.\n\nWIRE FORMAT (compact): responses that include nodes/edges use short keys and edge-by-index refs to cut payload ~40-60%. Every such response carries a `_schema` legend. Quick reference:\n  nodes[]: { i: id, t: type, n: name, m: module, r: route, mt: methods, x: exports, c: columns }\n  edges[]: { s: source_node_index, d: target_node_index, t: type, l: label }\nedges.s / edges.d are 0-based indices into THIS response\'s nodes array. If a referenced node is not in the response (boundary case), s/d may instead contain the full node id string \u2014 always check the type.\n\nBUDGET GUARDS:\n- Neighborhood queries stop expanding when the projected response exceeds budget. The response then contains `budget_exceeded: true` plus `hops_traversed < hops_requested`. When this happens, drill into a specific neighbor with another node_id call rather than retrying with larger hops \u2014 it will just truncate again.\n- Batch mode caps total response size. Once the budget is hit, later queries return `{skipped: true, reason: "batch_budget_exhausted"}` and you must re-run them individually.',
     inputSchema: {
       type: "object",
       properties: {
@@ -7475,11 +7475,15 @@ var TOOLS = [
         },
         minimal: {
           type: "boolean",
-          description: "Return minimal node fields only (id, type, name, module, route). Default false."
+          description: "Return minimal node fields only (id, type, name, module, route). Default false, except db-layer filter queries default to true (db table nodes carry heavy `columns` arrays). Pass minimal:false on a db filter query if you want columns."
+        },
+        include_edges: {
+          type: "boolean",
+          description: "Include the edge list in the response. Default TRUE for neighborhood queries (node_id), FALSE for filter queries. Filter responses always include edge_count. Only set true on filter queries when you actually need edge data."
         },
         queries: {
           type: "array",
-          description: "Batch mode \u2014 array of query objects to run in a single call. Each uses the same param schema (layer/search/type/module/node_id/hops/minimal). When set, top-level params are ignored.",
+          description: "Batch mode \u2014 array of query objects to run in a single call. Each uses the same param schema. When set, top-level params are ignored. Subject to an aggregate size budget \u2014 later queries may return a skipped stub.",
           items: {
             type: "object",
             properties: {
@@ -7489,7 +7493,8 @@ var TOOLS = [
               module: { type: "string" },
               node_id: { type: "string" },
               hops: { type: "number" },
-              minimal: { type: "boolean" }
+              minimal: { type: "boolean" },
+              include_edges: { type: "boolean" }
             }
           }
         }
@@ -7556,30 +7561,134 @@ function matchesSearch(node, query) {
 function toMinimal(nodes) {
   return nodes.map((n) => {
     const out = { id: n.id, type: n.type, name: n.name };
-    if (n.module) out.module = n.module;
-    if (n.route) out.route = n.route;
-    if (n.methods) out.methods = n.methods;
+    if (n.module != null) out.module = n.module;
+    if (n.route != null) out.route = n.route;
+    if (n.methods != null) out.methods = n.methods;
     return out;
   });
 }
-function neighborhood(graph, centerId, hops) {
+var COMPACT_SCHEMA = {
+  nodes: {
+    i: "id",
+    t: "type",
+    n: "name",
+    m: "module",
+    r: "route",
+    mt: "methods",
+    x: "exports",
+    c: "columns"
+  },
+  edges: {
+    s: "source_node_index",
+    d: "target_node_index",
+    t: "type",
+    l: "label"
+  },
+  note: "edges.s/d are 0-based indices into this response's nodes array. If a referenced node is outside the response (boundary case), s/d may contain the full node id string instead of an index."
+};
+var COMPACT_NODE_KNOWN_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "type",
+  "name",
+  "module",
+  "route",
+  "methods",
+  "exports",
+  "columns"
+]);
+var EST_CHARS_PER_NODE_FULL = {
+  ui: 300,
+  api: 300,
+  db: 3500
+};
+var EST_CHARS_PER_NODE_MIN = {
+  ui: 150,
+  api: 200,
+  db: 120
+};
+var EST_CHARS_PER_EDGE = {
+  ui: 65,
+  api: 65,
+  db: 65
+};
+var NEIGHBORHOOD_BUDGET_CHARS = 55e3;
+var BATCH_BUDGET_CHARS = 6e4;
+function toCompactNode(n) {
+  const out = { i: n.id, t: n.type, n: n.name };
+  if (n.module != null) out.m = n.module;
+  if (n.route != null) out.r = n.route;
+  if (n.methods != null) out.mt = n.methods;
+  if (n.exports != null) out.x = n.exports;
+  if (n.columns != null) out.c = n.columns;
+  for (const k of Object.keys(n)) {
+    if (!COMPACT_NODE_KNOWN_KEYS.has(k) && n[k] != null) out[k] = n[k];
+  }
+  return out;
+}
+function toCompactEdges(edges, idx) {
+  return edges.map((e) => {
+    const s = idx.get(e.source);
+    const d = idx.get(e.target);
+    const o = {
+      s: s ?? e.source,
+      d: d ?? e.target,
+      t: e.type
+    };
+    if (e.label != null) o.l = e.label;
+    return o;
+  });
+}
+function compactResult(raw) {
+  const nodes = raw.nodes;
+  if (!nodes) return raw;
+  const idx = /* @__PURE__ */ new Map();
+  nodes.forEach((n, i) => idx.set(n.id, i));
+  const compactNodes = nodes.map(toCompactNode);
+  const edges = raw.edges;
+  const compactEdges = edges ? toCompactEdges(edges, idx) : void 0;
+  const out = { _schema: COMPACT_SCHEMA };
+  for (const [k, v] of Object.entries(raw)) {
+    if (k === "nodes" || k === "edges") continue;
+    out[k] = v;
+  }
+  out.nodes = compactNodes;
+  if (compactEdges !== void 0) out.edges = compactEdges;
+  return out;
+}
+function neighborhood(graph, centerId, hops, layer, minimal) {
   const center = graph.nodes.find((n) => n.id === centerId);
   if (!center) return null;
   const visited = /* @__PURE__ */ new Set([centerId]);
   let frontier = /* @__PURE__ */ new Set([centerId]);
+  let budgetExceeded = false;
+  let stoppedAtHop = 0;
   for (let h = 0; h < hops; h++) {
     const next = /* @__PURE__ */ new Set();
     for (const edge of graph.edges) {
       if (frontier.has(edge.source) && !visited.has(edge.target)) next.add(edge.target);
       if (frontier.has(edge.target) && !visited.has(edge.source)) next.add(edge.source);
     }
+    const projectedVisited = visited.size + next.size;
+    let projectedEdges = 0;
+    for (const e of graph.edges) {
+      const srcIn = visited.has(e.source) || next.has(e.source);
+      const dstIn = visited.has(e.target) || next.has(e.target);
+      if (srcIn && dstIn) projectedEdges++;
+    }
+    const perNode = minimal ? EST_CHARS_PER_NODE_MIN[layer] : EST_CHARS_PER_NODE_FULL[layer];
+    const projectedChars = projectedVisited * perNode + projectedEdges * EST_CHARS_PER_EDGE[layer];
+    if (projectedChars > NEIGHBORHOOD_BUDGET_CHARS) {
+      budgetExceeded = true;
+      break;
+    }
     for (const id of next) visited.add(id);
     frontier = next;
+    stoppedAtHop = h + 1;
     if (frontier.size === 0) break;
   }
   const nodes = graph.nodes.filter((n) => visited.has(n.id));
   const edges = graph.edges.filter((e) => visited.has(e.source) && visited.has(e.target));
-  return { nodes, edges };
+  return { nodes, edges, budgetExceeded, stoppedAtHop };
 }
 function layerSummary(graph) {
   const typeCounts = {};
@@ -7638,14 +7747,16 @@ Output: .launchsecure/graphs/
 Use read_graph with filters (search/type/module/node_id) to query.`
   );
 }
-function runReadGraphQuery(rootDir, args) {
+function runReadGraphQueryRaw(rootDir, args) {
   const layer = args.layer;
   const search = args.search;
   const type = args.type;
   const module_ = args.module;
   const nodeId = args.node_id;
   const hops = args.hops ?? 1;
-  const minimal = args.minimal ?? false;
+  const layerIsDb = args.layer === "db";
+  const minimal = args.minimal ?? layerIsDb;
+  const includeEdges = args.include_edges;
   const hasFilter = !!(search || type || module_ || nodeId);
   if (layer && !["ui", "api", "db"].includes(layer)) {
     return { error: `Invalid layer "${layer}". Must be one of: ui, api, db` };
@@ -7671,19 +7782,26 @@ function runReadGraphQuery(rootDir, args) {
     return { error: `No ${layer} graph found at .launchsecure/graphs/${layer}.json. Run generate_graph first.` };
   }
   if (nodeId) {
-    const nb = neighborhood(graph, nodeId, hops);
+    const nb = neighborhood(graph, nodeId, hops, layer, minimal);
     if (!nb) {
       return { error: `Node "${nodeId}" not found in ${layer} graph. Try read_graph with search="${nodeId}" to find similar nodes.` };
     }
-    return {
+    const wantEdges2 = includeEdges ?? true;
+    const result2 = {
       layer,
       center: nodeId,
-      hops,
+      hops_requested: hops,
+      hops_traversed: nb.stoppedAtHop,
       node_count: nb.nodes.length,
       edge_count: nb.edges.length,
-      nodes: minimal ? toMinimal(nb.nodes) : nb.nodes,
-      edges: nb.edges
+      nodes: minimal ? toMinimal(nb.nodes) : nb.nodes
     };
+    if (wantEdges2) result2.edges = nb.edges;
+    if (nb.budgetExceeded) {
+      result2.budget_exceeded = true;
+      result2.hint = `Neighborhood truncated at hop ${nb.stoppedAtHop} (projected size exceeded budget). To explore further, call read_graph with node_id set to a specific neighbor from the returned nodes, or rerun with hops=${Math.max(1, nb.stoppedAtHop)} to confirm the partial view is what you wanted.`;
+    }
+    return result2;
   }
   if (!hasFilter) {
     return {
@@ -7708,14 +7826,24 @@ function runReadGraphQuery(rootDir, args) {
       hint: "No nodes matched. Check spelling, or call read_graph without filter to see the summary and available types/modules."
     };
   }
-  return {
+  const wantEdges = includeEdges ?? false;
+  const result = {
     layer,
     filter: { search, type, module: module_ },
     matched: matched.length,
     edge_count: matchedEdges.length,
-    nodes: minimal ? toMinimal(matched) : matched,
-    edges: matchedEdges
+    nodes: minimal ? toMinimal(matched) : matched
   };
+  if (wantEdges) {
+    result.edges = matchedEdges;
+  } else {
+    result.edges_hint = `${matchedEdges.length} edges between matched nodes omitted. Pass include_edges:true to retrieve them (only do this when you actually need edge data).`;
+  }
+  return result;
+}
+function runReadGraphQuery(rootDir, args) {
+  const raw = runReadGraphQueryRaw(rootDir, args);
+  return compactResult(raw);
 }
 function handleReadGraph(args) {
   const rootDir = process.cwd();
@@ -7724,8 +7852,49 @@ function handleReadGraph(args) {
     if (queries.length === 0) {
       return err("queries array is empty. Provide at least one query object.");
     }
-    const results = queries.map((q, i) => ({ index: i, query: q, result: runReadGraphQuery(rootDir, q) }));
-    return okJson({ batch: true, count: results.length, results });
+    const results = [];
+    let cumulativeChars = 0;
+    let budgetHit = false;
+    for (let i = 0; i < queries.length; i++) {
+      const q = queries[i];
+      if (budgetHit) {
+        results.push({
+          index: i,
+          query: q,
+          result: {
+            skipped: true,
+            reason: "batch_budget_exhausted",
+            hint: "Previous sub-results filled the batch budget. Re-run this query on its own."
+          }
+        });
+        continue;
+      }
+      const r = runReadGraphQuery(rootDir, q);
+      const entry = { index: i, query: q, result: r };
+      const entrySize = JSON.stringify(entry, null, 2).length;
+      if (cumulativeChars + entrySize > BATCH_BUDGET_CHARS && results.length > 0) {
+        budgetHit = true;
+        results.push({
+          index: i,
+          query: q,
+          result: {
+            skipped: true,
+            reason: "batch_budget_exhausted",
+            hint: "This sub-query would push the batch over its size budget. Re-run it on its own."
+          }
+        });
+      } else {
+        results.push(entry);
+        cumulativeChars += entrySize;
+      }
+    }
+    return okJson({
+      batch: true,
+      count: results.length,
+      cumulative_chars: cumulativeChars,
+      budget_hit: budgetHit,
+      results
+    });
   }
   const result = runReadGraphQuery(rootDir, args);
   return okJson(result);
@@ -7755,7 +7924,7 @@ function handleGrepNodes(args) {
   } catch (e) {
     return err(`Invalid regex: ${e.message}`);
   }
-  const queryResult = runReadGraphQuery(rootDir, {
+  const queryResult = runReadGraphQueryRaw(rootDir, {
     layer,
     search: args.search,
     type: args.type,

package/dist/server/graph-mcp-entry.js

@@ -1069,7 +1069,7 @@ var TOOLS = [
   },
   {
     name: "read_graph",
-    description: 'Query the structural project graph \u2014 a smart Glob replacement that locates files by type/module/name and returns structural metadata (imports, renders, routes, relations). \n\nUSE THIS FOR: "where is X", "what files are in module Y", "what pages exist under /admin", "what components does Z render", "what tables relate to User", "list all hooks in auth module". \n\nDO NOT USE FOR: finding text/code content (use Grep), reading actual source code (use Read), understanding behavior/logic/patterns (graph has no code semantics \u2014 only names and edges). \n\nQUERY PARAMS (at least one required for node data \u2014 unfiltered calls return summary only to stay in context):\n- search: substring match on node id, name, or route\n- type: filter by node type (ui layer: page, layout, component, ui, hook, context, config, util; api layer: endpoint; db layer: table, enum)\n- module: filter by module (ui layer only: auth, admin, project, org, settings, integrations, shared-ui, layout, root)\n- node_id: return this node + its neighborhood (incoming+outgoing edges within `hops`)\n- hops: neighborhood radius when node_id is set (default 1)\n- minimal: return only id/type/name/module/route per node (skip heavy fields like columns, exports)\n\nBATCH MODE: pass `queries` (array of query objects) to run multiple independent queries in a single call. Each query object uses the same params (layer/search/type/module/node_id/hops/minimal). Returns { batch: true, count, results: [{index, query, result}, ...] }. Use this when you need multiple graph views up-front (e.g. scoping a feature across ui+api+db layers) to save round-trips. When batch mode is used, top-level params are ignored.\n\nReturns: filtered nodes + edges between them. If no filter given, returns per-layer counts and type breakdown only.',
+    description: 'Query the structural project graph \u2014 a smart Glob replacement that locates files by type/module/name and returns structural metadata (imports, renders, routes, relations). \n\nUSE THIS FOR: "where is X", "what files are in module Y", "what pages exist under /admin", "what components does Z render", "what tables relate to User", "list all hooks in auth module". \n\nDO NOT USE FOR: finding text/code content (use Grep), reading actual source code (use Read), understanding behavior/logic/patterns (graph has no code semantics \u2014 only names and edges). \n\nQUERY PARAMS (at least one required for node data \u2014 unfiltered calls return summary only to stay in context):\n- search: substring match on node id, name, or route\n- type: filter by node type (ui layer: page, layout, component, ui, hook, context, config, util; api layer: endpoint; db layer: table, enum)\n- module: filter by module (ui layer only: auth, admin, project, org, settings, integrations, shared-ui, layout, root)\n- node_id: return this node + its neighborhood (incoming+outgoing edges within `hops`)\n- hops: neighborhood radius when node_id is set (default 1)\n- minimal: return only id/type/name/module/route per node (skip heavy fields like columns, exports)\n- include_edges: return the actual edge list. Default: TRUE for neighborhood queries (node_id), FALSE for filter queries (search/type/module). Filter responses always include `edge_count`; only pass include_edges:true when you actually need to inspect individual edges (e.g. "which components render X"). This default cuts typical filter responses in half.\n\nBATCH MODE: pass `queries` (array of query objects) to run multiple independent queries in a single call. Each query object uses the same params (layer/search/type/module/node_id/hops/minimal). Returns { batch: true, count, results: [{index, query, result}, ...] }. Use this when you need multiple graph views up-front (e.g. scoping a feature across ui+api+db layers) to save round-trips. When batch mode is used, top-level params are ignored.\n\nReturns: filtered nodes + edges between them. If no filter given, returns per-layer counts and type breakdown only.\n\nWIRE FORMAT (compact): responses that include nodes/edges use short keys and edge-by-index refs to cut payload ~40-60%. Every such response carries a `_schema` legend. Quick reference:\n  nodes[]: { i: id, t: type, n: name, m: module, r: route, mt: methods, x: exports, c: columns }\n  edges[]: { s: source_node_index, d: target_node_index, t: type, l: label }\nedges.s / edges.d are 0-based indices into THIS response\'s nodes array. If a referenced node is not in the response (boundary case), s/d may instead contain the full node id string \u2014 always check the type.\n\nBUDGET GUARDS:\n- Neighborhood queries stop expanding when the projected response exceeds budget. The response then contains `budget_exceeded: true` plus `hops_traversed < hops_requested`. When this happens, drill into a specific neighbor with another node_id call rather than retrying with larger hops \u2014 it will just truncate again.\n- Batch mode caps total response size. Once the budget is hit, later queries return `{skipped: true, reason: "batch_budget_exhausted"}` and you must re-run them individually.',
     inputSchema: {
       type: "object",
       properties: {
@@ -1100,11 +1100,15 @@ var TOOLS = [
         },
         minimal: {
           type: "boolean",
-          description: "Return minimal node fields only (id, type, name, module, route). Default false."
+          description: "Return minimal node fields only (id, type, name, module, route). Default false, except db-layer filter queries default to true (db table nodes carry heavy `columns` arrays). Pass minimal:false on a db filter query if you want columns."
+        },
+        include_edges: {
+          type: "boolean",
+          description: "Include the edge list in the response. Default TRUE for neighborhood queries (node_id), FALSE for filter queries. Filter responses always include edge_count. Only set true on filter queries when you actually need edge data."
         },
         queries: {
           type: "array",
-          description: "Batch mode \u2014 array of query objects to run in a single call. Each uses the same param schema (layer/search/type/module/node_id/hops/minimal). When set, top-level params are ignored.",
+          description: "Batch mode \u2014 array of query objects to run in a single call. Each uses the same param schema. When set, top-level params are ignored. Subject to an aggregate size budget \u2014 later queries may return a skipped stub.",
           items: {
             type: "object",
             properties: {
@@ -1114,7 +1118,8 @@ var TOOLS = [
               module: { type: "string" },
               node_id: { type: "string" },
               hops: { type: "number" },
-              minimal: { type: "boolean" }
+              minimal: { type: "boolean" },
+              include_edges: { type: "boolean" }
             }
           }
         }
@@ -1181,30 +1186,134 @@ function matchesSearch(node, query) {
 function toMinimal(nodes) {
   return nodes.map((n) => {
     const out = { id: n.id, type: n.type, name: n.name };
-    if (n.module) out.module = n.module;
-    if (n.route) out.route = n.route;
-    if (n.methods) out.methods = n.methods;
+    if (n.module != null) out.module = n.module;
+    if (n.route != null) out.route = n.route;
+    if (n.methods != null) out.methods = n.methods;
     return out;
   });
 }
-function neighborhood(graph, centerId, hops) {
+var COMPACT_SCHEMA = {
+  nodes: {
+    i: "id",
+    t: "type",
+    n: "name",
+    m: "module",
+    r: "route",
+    mt: "methods",
+    x: "exports",
+    c: "columns"
+  },
+  edges: {
+    s: "source_node_index",
+    d: "target_node_index",
+    t: "type",
+    l: "label"
+  },
+  note: "edges.s/d are 0-based indices into this response's nodes array. If a referenced node is outside the response (boundary case), s/d may contain the full node id string instead of an index."
+};
+var COMPACT_NODE_KNOWN_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "type",
+  "name",
+  "module",
+  "route",
+  "methods",
+  "exports",
+  "columns"
+]);
+var EST_CHARS_PER_NODE_FULL = {
+  ui: 300,
+  api: 300,
+  db: 3500
+};
+var EST_CHARS_PER_NODE_MIN = {
+  ui: 150,
+  api: 200,
+  db: 120
+};
+var EST_CHARS_PER_EDGE = {
+  ui: 65,
+  api: 65,
+  db: 65
+};
+var NEIGHBORHOOD_BUDGET_CHARS = 55e3;
+var BATCH_BUDGET_CHARS = 6e4;
+function toCompactNode(n) {
+  const out = { i: n.id, t: n.type, n: n.name };
+  if (n.module != null) out.m = n.module;
+  if (n.route != null) out.r = n.route;
+  if (n.methods != null) out.mt = n.methods;
+  if (n.exports != null) out.x = n.exports;
+  if (n.columns != null) out.c = n.columns;
+  for (const k of Object.keys(n)) {
+    if (!COMPACT_NODE_KNOWN_KEYS.has(k) && n[k] != null) out[k] = n[k];
+  }
+  return out;
+}
+function toCompactEdges(edges, idx) {
+  return edges.map((e) => {
+    const s = idx.get(e.source);
+    const d = idx.get(e.target);
+    const o = {
+      s: s ?? e.source,
+      d: d ?? e.target,
+      t: e.type
+    };
+    if (e.label != null) o.l = e.label;
+    return o;
+  });
+}
+function compactResult(raw) {
+  const nodes = raw.nodes;
+  if (!nodes) return raw;
+  const idx = /* @__PURE__ */ new Map();
+  nodes.forEach((n, i) => idx.set(n.id, i));
+  const compactNodes = nodes.map(toCompactNode);
+  const edges = raw.edges;
+  const compactEdges = edges ? toCompactEdges(edges, idx) : void 0;
+  const out = { _schema: COMPACT_SCHEMA };
+  for (const [k, v] of Object.entries(raw)) {
+    if (k === "nodes" || k === "edges") continue;
+    out[k] = v;
+  }
+  out.nodes = compactNodes;
+  if (compactEdges !== void 0) out.edges = compactEdges;
+  return out;
+}
+function neighborhood(graph, centerId, hops, layer, minimal) {
   const center = graph.nodes.find((n) => n.id === centerId);
   if (!center) return null;
   const visited = /* @__PURE__ */ new Set([centerId]);
   let frontier = /* @__PURE__ */ new Set([centerId]);
+  let budgetExceeded = false;
+  let stoppedAtHop = 0;
   for (let h = 0; h < hops; h++) {
     const next = /* @__PURE__ */ new Set();
     for (const edge of graph.edges) {
       if (frontier.has(edge.source) && !visited.has(edge.target)) next.add(edge.target);
       if (frontier.has(edge.target) && !visited.has(edge.source)) next.add(edge.source);
     }
+    const projectedVisited = visited.size + next.size;
+    let projectedEdges = 0;
+    for (const e of graph.edges) {
+      const srcIn = visited.has(e.source) || next.has(e.source);
+      const dstIn = visited.has(e.target) || next.has(e.target);
+      if (srcIn && dstIn) projectedEdges++;
+    }
+    const perNode = minimal ? EST_CHARS_PER_NODE_MIN[layer] : EST_CHARS_PER_NODE_FULL[layer];
+    const projectedChars = projectedVisited * perNode + projectedEdges * EST_CHARS_PER_EDGE[layer];
+    if (projectedChars > NEIGHBORHOOD_BUDGET_CHARS) {
+      budgetExceeded = true;
+      break;
+    }
     for (const id of next) visited.add(id);
     frontier = next;
+    stoppedAtHop = h + 1;
     if (frontier.size === 0) break;
   }
   const nodes = graph.nodes.filter((n) => visited.has(n.id));
   const edges = graph.edges.filter((e) => visited.has(e.source) && visited.has(e.target));
-  return { nodes, edges };
+  return { nodes, edges, budgetExceeded, stoppedAtHop };
 }
 function layerSummary(graph) {
   const typeCounts = {};
@@ -1263,14 +1372,16 @@ Output: .launchsecure/graphs/
 Use read_graph with filters (search/type/module/node_id) to query.`
   );
 }
-function runReadGraphQuery(rootDir, args) {
+function runReadGraphQueryRaw(rootDir, args) {
   const layer = args.layer;
   const search = args.search;
   const type = args.type;
   const module_ = args.module;
   const nodeId = args.node_id;
   const hops = args.hops ?? 1;
-  const minimal = args.minimal ?? false;
+  const layerIsDb = args.layer === "db";
+  const minimal = args.minimal ?? layerIsDb;
+  const includeEdges = args.include_edges;
   const hasFilter = !!(search || type || module_ || nodeId);
   if (layer && !["ui", "api", "db"].includes(layer)) {
     return { error: `Invalid layer "${layer}". Must be one of: ui, api, db` };
@@ -1296,19 +1407,26 @@ function runReadGraphQuery(rootDir, args) {
     return { error: `No ${layer} graph found at .launchsecure/graphs/${layer}.json. Run generate_graph first.` };
   }
   if (nodeId) {
-    const nb = neighborhood(graph, nodeId, hops);
+    const nb = neighborhood(graph, nodeId, hops, layer, minimal);
     if (!nb) {
       return { error: `Node "${nodeId}" not found in ${layer} graph. Try read_graph with search="${nodeId}" to find similar nodes.` };
     }
-    return {
+    const wantEdges2 = includeEdges ?? true;
+    const result2 = {
       layer,
       center: nodeId,
-      hops,
+      hops_requested: hops,
+      hops_traversed: nb.stoppedAtHop,
       node_count: nb.nodes.length,
       edge_count: nb.edges.length,
-      nodes: minimal ? toMinimal(nb.nodes) : nb.nodes,
-      edges: nb.edges
+      nodes: minimal ? toMinimal(nb.nodes) : nb.nodes
     };
+    if (wantEdges2) result2.edges = nb.edges;
+    if (nb.budgetExceeded) {
+      result2.budget_exceeded = true;
+      result2.hint = `Neighborhood truncated at hop ${nb.stoppedAtHop} (projected size exceeded budget). To explore further, call read_graph with node_id set to a specific neighbor from the returned nodes, or rerun with hops=${Math.max(1, nb.stoppedAtHop)} to confirm the partial view is what you wanted.`;
+    }
+    return result2;
   }
   if (!hasFilter) {
     return {
@@ -1333,14 +1451,24 @@ function runReadGraphQuery(rootDir, args) {
       hint: "No nodes matched. Check spelling, or call read_graph without filter to see the summary and available types/modules."
     };
   }
-  return {
+  const wantEdges = includeEdges ?? false;
+  const result = {
     layer,
     filter: { search, type, module: module_ },
     matched: matched.length,
     edge_count: matchedEdges.length,
-    nodes: minimal ? toMinimal(matched) : matched,
-    edges: matchedEdges
+    nodes: minimal ? toMinimal(matched) : matched
   };
+  if (wantEdges) {
+    result.edges = matchedEdges;
+  } else {
+    result.edges_hint = `${matchedEdges.length} edges between matched nodes omitted. Pass include_edges:true to retrieve them (only do this when you actually need edge data).`;
+  }
+  return result;
+}
+function runReadGraphQuery(rootDir, args) {
+  const raw = runReadGraphQueryRaw(rootDir, args);
+  return compactResult(raw);
 }
 function handleReadGraph(args) {
   const rootDir = process.cwd();
@@ -1349,8 +1477,49 @@ function handleReadGraph(args) {
     if (queries.length === 0) {
       return err("queries array is empty. Provide at least one query object.");
     }
-    const results = queries.map((q, i) => ({ index: i, query: q, result: runReadGraphQuery(rootDir, q) }));
-    return okJson({ batch: true, count: results.length, results });
+    const results = [];
+    let cumulativeChars = 0;
+    let budgetHit = false;
+    for (let i = 0; i < queries.length; i++) {
+      const q = queries[i];
+      if (budgetHit) {
+        results.push({
+          index: i,
+          query: q,
+          result: {
+            skipped: true,
+            reason: "batch_budget_exhausted",
+            hint: "Previous sub-results filled the batch budget. Re-run this query on its own."
+          }
+        });
+        continue;
+      }
+      const r = runReadGraphQuery(rootDir, q);
+      const entry = { index: i, query: q, result: r };
+      const entrySize = JSON.stringify(entry, null, 2).length;
+      if (cumulativeChars + entrySize > BATCH_BUDGET_CHARS && results.length > 0) {
+        budgetHit = true;
+        results.push({
+          index: i,
+          query: q,
+          result: {
+            skipped: true,
+            reason: "batch_budget_exhausted",
+            hint: "This sub-query would push the batch over its size budget. Re-run it on its own."
+          }
+        });
+      } else {
+        results.push(entry);
+        cumulativeChars += entrySize;
+      }
+    }
+    return okJson({
+      batch: true,
+      count: results.length,
+      cumulative_chars: cumulativeChars,
+      budget_hit: budgetHit,
+      results
+    });
   }
   const result = runReadGraphQuery(rootDir, args);
   return okJson(result);
@@ -1380,7 +1549,7 @@ function handleGrepNodes(args) {
   } catch (e) {
     return err(`Invalid regex: ${e.message}`);
   }
-  const queryResult = runReadGraphQuery(rootDir, {
+  const queryResult = runReadGraphQueryRaw(rootDir, {
     layer,
     search: args.search,
     type: args.type,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchsecure/launch-kit",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "LaunchSecure toolkit — launch-pod (pipeline pod), launch-chart (project graph MCP), and more.",
   "license": "MIT",
   "author": "LaunchSecure - AutomateWithUs",