@jefuriiij/synthra 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ For older versions, see [GitHub Releases](https://github.com/jefuriiij/synthra/r
 
 ---
 
+## [0.4.0] — 2026-06-10
+
+### Changed
+
+- **The Moat's block messages now deliver the answer, not just directions.**
+  When the gate blocks a Grep/Glob, the deny reason used to name the relevant
+  file paths — and agents responded by Reading those files whole, erasing the
+  savings the block was meant to create. The block message now carries
+  copy-pasteable `mcp__synthra__graph_read("file::symbol")` targets with
+  one-line signatures for the query's best-matching symbols (~300 tokens,
+  signatures only), plus a `graph_continue` pointer for the full pack. The
+  cheap path is now the path of least resistance. Budget tunable via
+  `SYN_GATE_HINT_CHARS` (default 1200 chars). Gate decisions are unchanged —
+  only the message got smarter.
+- **Policy v7 — full namespaced tool names.** Agents wasted tool-discovery
+  round-trips searching for short names like `graph_continue` that don't
+  resolve. The CLAUDE.md policy block now states the `mcp__synthra__` namespace
+  requirement up front, provides a ready ToolSearch `select:` line for the
+  graph tools, and uses the full form in every invocation example. Existing
+  policy blocks upgrade automatically on the next `syn .`.
+
+---
+
 ## [0.3.1] — 2026-06-09
 
 ### Changed

package/dist/cli/index.js

@@ -18,7 +18,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@jefuriiij/synthra",
-      version: "0.3.1",
+      version: "0.4.0",
       publishConfig: {
         access: "public"
       },
@@ -3732,7 +3732,7 @@ import { basename as basename4 } from "path";
 // src/hooks/claude-md.ts
 import { readFile as readFile11, writeFile as writeFile6 } from "fs/promises";
 import { basename as basename3, dirname as dirname8 } from "path";
-var POLICY_VERSION = 6;
+var POLICY_VERSION = 7;
 var POLICY_BEGIN = `<!-- synthra-policy v${POLICY_VERSION} BEGIN -->`;
 var POLICY_END = `<!-- synthra-policy v${POLICY_VERSION} END -->`;
 var ANY_BLOCK_RE = /<!--\s*synthra-policy\s+v\d+\s+BEGIN\s*-->[\s\S]*?<!--\s*synthra-policy\s+v\d+\s+END\s*-->\s*/g;
@@ -3748,9 +3748,12 @@ function policyBlock() {
     "",
     "> **Tool namespace.** Synthra's MCP tools are exposed as",
     "> `mcp__synthra__graph_continue`, `mcp__synthra__graph_read`, and",
-    "> `mcp__synthra__graph_register_edit`. Below they are referred to by",
-    "> their short names (`graph_continue` etc.) for readability \u2014 use the",
-    "> full namespaced form when actually invoking them.",
+    "> `mcp__synthra__graph_register_edit`. **Short names will NOT resolve**",
+    "> in ToolSearch or invocation \u2014 always use the full namespaced form.",
+    "> If the tools are deferred, load their schemas with ToolSearch:",
+    "> `select:mcp__synthra__graph_continue,mcp__synthra__graph_read,mcp__synthra__graph_register_edit`.",
+    "> Below, short names (`graph_continue` etc.) appear in prose for",
+    "> readability only.",
     "",
     "### Tools",
     "",
@@ -3779,8 +3782,8 @@ function policyBlock() {
     "  test, docs, cleanup, commit)",
     "- The task is pure text (commit message, explanation, summary)",
     "",
-    'If skipping, go directly to `graph_read("file.ts::symbol")` on what',
-    "you already know.",
+    "If skipping, go directly to",
+    '`mcp__synthra__graph_read("file.ts::symbol")` on what you already know.',
     "",
     "### Confidence caps",
     "",
@@ -3789,8 +3792,8 @@ function policyBlock() {
     "- **`Confidence: high`** \u2192 Stop. Do NOT Grep, Glob, or further explore",
     "  for this query. The graph already has it.",
     "- **`Confidence: medium`** \u2192 Read the listed `Files` directly via",
-    '  `graph_read("file::symbol")` *before* trying Grep. The graph has',
-    "  narrowed the search space \u2014 use it, don't bypass it.",
+    '  `mcp__synthra__graph_read("file::symbol")` *before* trying Grep. The',
+    "  graph has narrowed the search space \u2014 use it, don't bypass it.",
     "- **`Confidence: low`** \u2192 You may use Grep / Glob, but the PreToolUse",
     "  hook may still block redundant calls.",
     "",
@@ -3801,8 +3804,9 @@ function policyBlock() {
     "- If `graph_continue`'s `Files` list contains a `::` entry, pass it",
     "  verbatim to `graph_read`.",
     "- **Large file?** Don't read it in successive line-range chunks \u2014 call",
-    '  `graph_continue` or `graph_read("file::symbol")` to pull the one symbol',
-    "  you need. Chunked whole-file Reads are exactly the cost `graph_read`",
+    "  `mcp__synthra__graph_continue` or",
+    '  `mcp__synthra__graph_read("file::symbol")` to pull the one symbol you',
+    "  need. Chunked whole-file Reads are exactly the cost `graph_read`",
     "  exists to avoid.",
     "",
     "### Editing a file",
@@ -3830,9 +3834,10 @@ function policyBlock() {
     "decisions carried over from the previous session. **Trust it.** It is the",
     "cheapest possible orientation: do NOT re-run `graph_continue` or Grep just",
     'to rediscover "what were we doing / what changed" \u2014 that work is already',
-    'done. For the concrete next steps, `context_recall({kind:"next"})` returns',
-    "them verbatim. Only reach for fresh retrieval when the task moves beyond",
-    "what the digest covers.",
+    "done. For the concrete next steps,",
+    '`mcp__synthra__context_recall({kind:"next"})` returns them verbatim. Only',
+    "reach for fresh retrieval when the task moves beyond what the digest",
+    "covers.",
     "",
     "### Session-end resume note",
     "",
@@ -5335,6 +5340,32 @@ async function handleContextUpdate(req, ctx) {
 // src/server/routes/gate.ts
 import { appendFile as appendFile4, mkdir as mkdir12 } from "fs/promises";
 import { dirname as dirname13 } from "path";
+
+// src/shared/config.ts
+function num(name, fallback) {
+  const v = process.env[name];
+  if (!v) return fallback;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+function str(name, fallback) {
+  return process.env[name] ?? fallback;
+}
+function loadConfig() {
+  return {
+    hardMaxReadChars: num("SYN_HARD_MAX_READ_CHARS", 4e3),
+    gateHintMaxChars: num("SYN_GATE_HINT_CHARS", 1200),
+    turnReadBudgetChars: num("SYN_TURN_READ_BUDGET_CHARS", 18e3),
+    fallbackMaxCallsPerTurn: num("SYN_FALLBACK_MAX_CALLS_PER_TURN", 1),
+    retrieveCacheTtlSec: num("SYN_RETRIEVE_CACHE_TTL_SEC", 900),
+    mcpPort: process.env.SYN_MCP_PORT ? num("SYN_MCP_PORT", 0) : null,
+    dashboardPort: num("SYN_DASHBOARD_PORT", 8901),
+    logLevel: str("SYN_LOG_LEVEL", "info"),
+    claudeBin: str("SYN_CLAUDE_BIN", "claude")
+  };
+}
+
+// src/server/routes/gate.ts
 var BLOCKABLE_TOOLS = /* @__PURE__ */ new Set(["Grep", "Glob"]);
 var RECENT_ACTIVITY_WINDOW_MS = 5 * 60 * 1e3;
 function extractQuery(toolName, input) {
@@ -5388,7 +5419,8 @@ function recentlyTouchedMatchesQuery(recentPaths, queryTokens, graph) {
   }
   return matches;
 }
-async function logDecision(ctx, toolName, query, decision, reason) {
+var LOG_REASON_MAX_CHARS = 240;
+async function logDecision(ctx, toolName, query, decision, reason, hintChars) {
   try {
     await mkdir12(dirname13(ctx.paths.gateLog), { recursive: true });
     const entry = {
@@ -5396,12 +5428,70 @@ async function logDecision(ctx, toolName, query, decision, reason) {
       tool: toolName,
       decision,
       query,
-      reason
+      reason: reason && reason.length > LOG_REASON_MAX_CHARS ? `${reason.slice(0, LOG_REASON_MAX_CHARS)}\u2026` : reason,
+      ...hintChars === void 0 ? {} : { hint_chars: hintChars }
     };
     await appendFile4(ctx.paths.gateLog, JSON.stringify(entry) + "\n", "utf8");
   } catch {
   }
 }
+var SIG_LINE_MAX_CHARS = 140;
+function scoreSymbolName(name, qTokens) {
+  const lower = name.toLowerCase();
+  let score2 = 0;
+  for (const t of qTokens) {
+    if (t === lower) score2 += 3;
+    else if (t.length >= 3 && lower.includes(t)) score2 += 1;
+  }
+  return score2;
+}
+function buildBlockHint(query, retrieval, graph, toolName, maxChars = loadConfig().gateHintMaxChars) {
+  const topFiles = retrieval.files.slice(0, 3);
+  const topPaths = new Set(topFiles.map((f) => f.path));
+  const symsByFile = /* @__PURE__ */ new Map();
+  for (const n of graph.nodes) {
+    if (n.kind !== "symbol" || !topPaths.has(n.file)) continue;
+    const list = symsByFile.get(n.file);
+    if (list) list.push(n);
+    else symsByFile.set(n.file, [n]);
+  }
+  const qTokens = tokenizeQuery(query);
+  const entries = [];
+  for (const f of topFiles) {
+    const syms = (symsByFile.get(f.path) ?? []).slice().sort((a, b) => a.start_line - b.start_line);
+    if (syms.length === 0) {
+      entries.push(`\u2022 mcp__synthra__graph_read("${f.path}")`);
+      continue;
+    }
+    const scored = syms.map((s) => ({ s, score: scoreSymbolName(s.name, qTokens) })).filter((x) => x.score > 0).sort((a, b) => b.score - a.score);
+    const picks = scored.length > 0 ? scored.slice(0, 2).map((x) => x.s) : syms.slice(0, 1);
+    for (const s of picks) {
+      const sig = `L${s.start_line}: ${s.signature.trim()}`;
+      const sigLine = sig.length > SIG_LINE_MAX_CHARS ? `${sig.slice(0, SIG_LINE_MAX_CHARS - 1)}\u2026` : sig;
+      entries.push(`\u2022 mcp__synthra__graph_read("${f.path}::${s.name}")
+  ${sigLine}`);
+    }
+  }
+  const header = `Synthra blocked this ${toolName} \u2014 ${retrieval.confidence}-confidence context for "${query}" already exists.
+Read symbols directly (~50 tokens each) instead of whole files:
+`;
+  const footer = `
+Full pack: mcp__synthra__graph_continue("${query}")`;
+  const parts = [];
+  let used = header.length + footer.length + 1;
+  for (const e of entries) {
+    if (used + e.length + 1 > maxChars) break;
+    parts.push(e);
+    used += e.length + 1;
+  }
+  if (parts.length === 0) {
+    const top = topFiles.map((f) => f.path).join(", ");
+    return `Synthra has ${retrieval.confidence}-confidence context for "${query}" (top files: ${top}). Use mcp__synthra__graph_continue("${query}") instead of ${toolName}, or read a specific file/symbol with mcp__synthra__graph_read.`;
+  }
+  return `${header}
+${parts.join("\n")}
+${footer}`;
+}
 async function handleGate(req, ctx) {
   if (!req?.tool_name || typeof req.tool_name !== "string") {
     return { decision: "allow", reason: "no tool_name" };
@@ -5452,12 +5542,9 @@ async function handleGate(req, ctx) {
     await logDecision(ctx, req.tool_name, query, res2.decision, res2.reason);
     return res2;
   }
-  const top = retrieval.files.slice(0, 3).map((f) => f.path).join(", ");
-  const res = {
-    decision: "block",
-    reason: `Synthra has ${retrieval.confidence}-confidence context for "${query}" (top files: ${top}). Use the \`graph_continue\` MCP tool with this query instead of ${req.tool_name}, or read a specific file/symbol with \`graph_read\`.`
-  };
-  await logDecision(ctx, req.tool_name, query, res.decision, res.reason);
+  const hint = buildBlockHint(query, retrieval, ctx.graph, req.tool_name);
+  const res = { decision: "block", reason: hint };
+  await logDecision(ctx, req.tool_name, query, res.decision, hint, hint.length);
   return res;
 }
 
@@ -5702,29 +5789,6 @@ async function startServer(paths, options = {}) {
   };
 }
 
-// src/shared/config.ts
-function num(name, fallback) {
-  const v = process.env[name];
-  if (!v) return fallback;
-  const n = Number(v);
-  return Number.isFinite(n) ? n : fallback;
-}
-function str(name, fallback) {
-  return process.env[name] ?? fallback;
-}
-function loadConfig() {
-  return {
-    hardMaxReadChars: num("SYN_HARD_MAX_READ_CHARS", 4e3),
-    turnReadBudgetChars: num("SYN_TURN_READ_BUDGET_CHARS", 18e3),
-    fallbackMaxCallsPerTurn: num("SYN_FALLBACK_MAX_CALLS_PER_TURN", 1),
-    retrieveCacheTtlSec: num("SYN_RETRIEVE_CACHE_TTL_SEC", 900),
-    mcpPort: process.env.SYN_MCP_PORT ? num("SYN_MCP_PORT", 0) : null,
-    dashboardPort: num("SYN_DASHBOARD_PORT", 8901),
-    logLevel: str("SYN_LOG_LEVEL", "info"),
-    claudeBin: str("SYN_CLAUDE_BIN", "claude")
-  };
-}
-
 // src/cli/session-discovery.ts
 import { readdir as readdir2, stat as stat3 } from "fs/promises";
 import { homedir as homedir2 } from "os";