drydock-cli 3.0.46__tar.gz → 3.0.49__tar.gz

{drydock_cli-3.0.46/drydock_cli.egg-info → drydock_cli-3.0.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 3.0.46
+Version: 3.0.49
 Summary: Drydock — a local, provider-agnostic terminal coding agent for local LLMs
 Author: Frank Bobe III
 License-Expression: Apache-2.0

{drydock_cli-3.0.46 → drydock_cli-3.0.49}/drydock/agent.py

@@ -19,7 +19,7 @@ def _plan_has_unfinished(config: dict) -> bool:
     todo = config.get("_todo")
     return bool(todo) and any(status != "done" for _, status in todo)
 
-from drydock.providers import stream, AssistantTurn, TextChunk
+from drydock.providers import stream, AssistantTurn, ReasoningChunk, TextChunk
 from drydock.tool_registry import schemas, execute
 from drydock.tools import register_all
 
@@ -168,7 +168,9 @@ def run(
                     tool_schemas=filter_tool_schemas(available, turn_config.get("model")),
                     config=turn_config,
                 ):
-                    if isinstance(event, TextChunk):
+                    if isinstance(event, ReasoningChunk):
+                        yield event
+                    elif isinstance(event, TextChunk):
                         yield event
                     elif isinstance(event, AssistantTurn):
                         assistant_turn = event

{drydock_cli-3.0.46 → drydock_cli-3.0.49}/drydock/cli.py

@@ -149,7 +149,8 @@ def run_oneshot(prompt: str, config: dict) -> None:
 
 def handle_command(cmd: str, state: AgentState, config: dict) -> bool:
     """Handle slash commands. Returns True if handled."""
-    cmd = cmd.lower().strip()
+    raw = cmd.strip()  # case-preserved (paths/args must not be lowercased)
+    cmd = raw.lower()
     if cmd == "/help":
         print_colored("Commands:", "bold")
         print("  /help     — show this help")
@@ -164,7 +165,7 @@ def handle_command(cmd: str, state: AgentState, config: dict) -> bool:
         print_colored("  Conversation cleared.", "green")
         return True
     elif cmd == "/compact":
-        from drydock.compaction import compact, estimate_tokens
+        from drydock.compaction import compact, emergency_compact, estimate_tokens
 
         if not state.messages:
             print_colored("  Nothing to compact.", "dim")
@@ -172,6 +173,8 @@ def handle_command(cmd: str, state: AgentState, config: dict) -> bool:
         before = estimate_tokens(state.messages)
         limit = config.get("context_limit", 65536) or 65536
         state.messages = compact(state.messages, limit)
+        if estimate_tokens(state.messages) > limit * 0.5:
+            state.messages = emergency_compact(state.messages, limit)
         after = estimate_tokens(state.messages)
         saved = before - after
         if saved > 0:
@@ -187,6 +190,37 @@ def handle_command(cmd: str, state: AgentState, config: dict) -> bool:
         print_colored(f"  Messages: {len(state.messages)}", "cyan")
         print_colored(f"  Tokens: {state.total_input_tokens}in / {state.total_output_tokens}out", "cyan")
         return True
+    elif cmd.split()[0] == "/graphrag":
+        from drydock import graphrag
+
+        cwd = config.get("cwd") or os.getcwd()
+        store = graphrag.default_store_path(cwd)
+        parts = raw.split()  # raw = case-preserved, so paths survive
+        sub = parts[1].lower() if len(parts) > 1 else ""
+        rest = " ".join(parts[2:]).strip()
+        if sub == "build" and rest:
+            print_colored(f"  Building knowledge base from {rest} …", "dim")
+            try:
+                stats = graphrag.build_index([rest], store, cwd=cwd)
+                print_colored(
+                    f"  ✓ {stats['files']} files · {stats['chunks']} chunks · "
+                    f"{stats['entities']} entities · {stats['edges']} edges → {store}",
+                    "green",
+                )
+            except Exception as e:  # noqa: BLE001
+                print_colored(f"  graphrag build failed: {e}", "red")
+        elif sub == "clear":
+            store.unlink(missing_ok=True)
+            print_colored("  Knowledge base cleared.", "green")
+        else:
+            index = graphrag.load_index(store)
+            if index is None:
+                print_colored("  No knowledge base. Build: /graphrag build <path>", "dim")
+            else:
+                print_colored(
+                    f"  Knowledge base: {len(index.get('chunks', []))} chunks · "
+                    f"{len(index.get('entities', {}))} entities ({store})", "cyan")
+        return True
     elif cmd in ("/quit", "/exit"):
         raise KeyboardInterrupt
     return False
@@ -246,6 +280,11 @@ def main():
     parser.add_argument("--provider", help="Provider: vllm, ollama, lmstudio, openai")
     parser.add_argument("--base-url", dest="base_url", help="Override API base URL")
     parser.add_argument("--max-tokens", dest="max_tokens", type=int, help="Max response tokens")
+    parser.add_argument(
+        "--context-limit", dest="context_limit", type=int,
+        help="Model server context window (must match the server's -c / "
+             "--max-model-len; drives the ctx gauge + when compaction fires)",
+    )
     parser.add_argument("--temperature", type=float)
     parser.add_argument("--max-tool-calls", type=int, default=0, help="Max tool calls (0=unlimited)")
     parser.add_argument("--force-first-tool", action="store_true", help="Force tool_choice=required on first turn")
@@ -268,6 +307,7 @@ def main():
         "base_url": args.base_url,
         "max_tokens": args.max_tokens,
         "temperature": args.temperature,
+        "context_limit": args.context_limit,
     }, cfg_path)
 
     # First launch: ask the user for their model server URL + model name and
@@ -288,10 +328,11 @@ def main():
                 cfgmod.save_file(cfg, cfg_path)
 
     config = {
+        # context_limit now comes from cfg (DEFAULTS < config.toml < --context-limit)
+        # — it drives the ctx gauge AND when compaction fires, so it must match the
+        # server's real -c. Previously hardcoded to 65536 here, which clobbered the
+        # config value and overflowed servers running a smaller window.
         **cfg,
-        # Match the llama.cpp server's -c (gemma4 runs at 64k). Drives both the
-        # status-bar context gauge and when compaction kicks in.
-        "context_limit": 65536,
         "max_tool_calls": args.max_tool_calls,
         "force_first_tool": args.force_first_tool,
         "_approve_all": args.dangerously_skip_permissions,

{drydock_cli-3.0.46 → drydock_cli-3.0.49}/drydock/config.py

@@ -28,6 +28,12 @@ DEFAULTS: dict[str, object] = {
     "base_url": "http://localhost:8000/v1",
     "max_tokens": 8192,  # 4096 truncated large file writes mid-JSON (→ _raw fail)
     "temperature": 0.2,
+    # The model server's context window (llama.cpp -c / vLLM --max-model-len).
+    # Drives the ctx gauge AND when compaction fires (it compacts at ~60% of
+    # this). It MUST match your server: if it's too high, drydock overflows the
+    # real window BEFORE compacting (the server 400s) — set this to your -c
+    # value. Default 65536 matches the bundled gemma4 server (-c 65536).
+    "context_limit": 65536,
     "theme": "harbor",
 }
 

{drydock_cli-3.0.46 → drydock_cli-3.0.49}/drydock/detect.py

@@ -63,7 +63,7 @@ def onboarding_message(found: list[dict]) -> str:
         return (
             "No local LLM detected (" + ports + "). Point Drydock at your model "
             "right here:\n"
-            "  /model url <http://host:port/v1>     then     /model <model-name>\n"
+            "  /model url <http://localhost:8000/v1>     then     /model <model-name>\n"
             "(saved to ~/.drydock/config.toml). Or start a local server "
             "(llama.cpp / vLLM / Ollama / LM Studio) and restart."
         )

drydock_cli-3.0.49/drydock/graphrag.py

@@ -0,0 +1,244 @@
+"""GraphRAG — a local, dependency-free knowledge graph for retrieval.
+
+The user builds an index from their own docs/code; the agent then queries it
+through the `Knowledge` tool while answering or coding, so it can ground its
+work in project-specific information the model was never trained on.
+
+Design (clean-room, stdlib only — no embeddings, no third-party deps, works
+against any server):
+  • Ingest text files → split into chunks.
+  • Extract ENTITIES from each chunk (proper nouns, `code` terms, CamelCase /
+    snake_case identifiers, ACRONYMS) → graph NODES.
+  • Entities co-occurring in a chunk get an EDGE (weighted by co-occurrence) →
+    the graph. Each entity also points at the chunks it appears in.
+  • Query: pull the query's entities + keywords, score chunks by entity and
+    keyword overlap, then EXPAND one hop along the entity graph so strongly
+    related context comes along — the "graph" in GraphRAG. Return the top
+    chunks plus the related entities, both fed back to the model.
+
+The index is a single JSON file so it's inspectable, portable, and gitignorable.
+
+All logic original to Drydock.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections import Counter, defaultdict
+from pathlib import Path
+
+# Files we ingest as text. Everything else (binaries, images) is skipped.
+_TEXT_EXT = {
+    ".md", ".txt", ".rst", ".py", ".js", ".ts", ".tsx", ".jsx", ".java", ".go",
+    ".rs", ".c", ".h", ".cpp", ".hpp", ".cs", ".rb", ".php", ".sh", ".toml",
+    ".yaml", ".yml", ".json", ".cfg", ".ini", ".sql", ".html", ".css", ".org",
+    ".tex", ".csv", ".log", ".",
+}
+_SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", "dist",
+              "build", ".mypy_cache", ".pytest_cache", ".drydock"}
+
+_STOPWORDS = frozenset("""
+the a an and or but if then else for while of to in on at by with from into as
+is are was were be been being do does did this that these those it its their
+your you we they he she his her our not no yes can will would should could may
+""".split())
+
+# Entity patterns (kept simple + fast; tuned to surface useful nodes, not noise)
+_RE_BACKTICK = re.compile(r"`([^`\n]{2,60})`")
+_RE_IDENT = re.compile(r"\b([a-zA-Z_][a-zA-Z0-9_]*(?:[_./][a-zA-Z0-9_]+)+)\b")
+_RE_CAMEL = re.compile(r"\b([A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)+)\b")
+_RE_PROPER = re.compile(r"\b([A-Z][a-zA-Z0-9]+(?:[ \t]+[A-Z][a-zA-Z0-9]+){0,3})\b")
+_RE_ACRONYM = re.compile(r"\b([A-Z]{2,6})\b")
+_RE_WORD = re.compile(r"[a-zA-Z0-9_]+")
+
+
+def default_store_path(cwd: str) -> Path:
+    """Project-local index (travels with the project, easy to .gitignore)."""
+    return Path(cwd) / ".drydock" / "graphrag.json"
+
+
+def extract_entities(text: str) -> list[str]:
+    """Heuristic entity extraction → normalized (lowercased) entity keys."""
+    found: set[str] = set()
+    for rx in (_RE_BACKTICK, _RE_IDENT, _RE_CAMEL, _RE_PROPER, _RE_ACRONYM):
+        for m in rx.findall(text):
+            e = m.strip().lower()
+            # Drop trivial / stopword-only entities and overlong noise.
+            if len(e) < 3 or len(e) > 60:
+                continue
+            if all(w in _STOPWORDS for w in _RE_WORD.findall(e)):
+                continue
+            found.add(e)
+    return sorted(found)
+
+
+def _chunk_text(text: str, max_chars: int = 1200) -> list[str]:
+    """Split into paragraph-ish chunks, capping size so a chunk stays focused."""
+    chunks: list[str] = []
+    buf: list[str] = []
+    size = 0
+    for para in re.split(r"\n\s*\n", text):
+        para = para.strip()
+        if not para:
+            continue
+        if size + len(para) > max_chars and buf:
+            chunks.append("\n\n".join(buf))
+            buf, size = [], 0
+        if len(para) > max_chars:  # a single huge paragraph → hard-split
+            for i in range(0, len(para), max_chars):
+                chunks.append(para[i:i + max_chars])
+            continue
+        buf.append(para)
+        size += len(para)
+    if buf:
+        chunks.append("\n\n".join(buf))
+    return chunks
+
+
+def _iter_text_files(paths: list[str]):
+    for p in paths:
+        path = Path(p)
+        if path.is_file():
+            yield path
+        elif path.is_dir():
+            for root, dirs, files in os.walk(path):
+                dirs[:] = [d for d in dirs if d not in _SKIP_DIRS]
+                for f in files:
+                    fp = Path(root) / f
+                    if fp.suffix.lower() in _TEXT_EXT or fp.suffix == "":
+                        yield fp
+
+
+def build_index(paths: list[str], store_path: str | Path, *, cwd: str = ".") -> dict:
+    """Build (or rebuild) the knowledge graph from paths; persist to store_path.
+
+    Returns a stats dict: {files, chunks, entities, edges}.
+    """
+    chunks: list[dict] = []
+    entity_chunks: dict[str, set[int]] = defaultdict(set)
+    edges: dict[str, Counter] = defaultdict(Counter)
+    files = 0
+
+    for fp in _iter_text_files([str(Path(cwd) / p) if not os.path.isabs(p) else p
+                                for p in paths]):
+        try:
+            text = fp.read_text("utf-8", "ignore")
+        except OSError:
+            continue
+        if not text.strip():
+            continue
+        files += 1
+        rel = os.path.relpath(str(fp), cwd)
+        for body in _chunk_text(text):
+            cid = len(chunks)
+            ents = extract_entities(body)
+            chunks.append({"id": cid, "source": rel, "text": body, "entities": ents})
+            for e in ents:
+                entity_chunks[e].add(cid)
+            for i, a in enumerate(ents):  # co-occurrence edges within the chunk
+                for b in ents[i + 1:]:
+                    edges[a][b] += 1
+                    edges[b][a] += 1
+
+    index = {
+        "version": 1,
+        "chunks": chunks,
+        "entities": {e: sorted(cids) for e, cids in entity_chunks.items()},
+        "edges": {a: dict(nbrs) for a, nbrs in edges.items()},
+    }
+    sp = Path(store_path)
+    sp.parent.mkdir(parents=True, exist_ok=True)
+    sp.write_text(json.dumps(index), encoding="utf-8")
+    return {
+        "files": files,
+        "chunks": len(chunks),
+        "entities": len(entity_chunks),
+        "edges": sum(len(v) for v in edges.values()) // 2,
+    }
+
+
+def load_index(store_path: str | Path) -> dict | None:
+    sp = Path(store_path)
+    if not sp.exists():
+        return None
+    try:
+        return json.loads(sp.read_text("utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def query_index(index: dict, query: str, *, k: int = 5, hops: bool = True) -> dict:
+    """Retrieve the top-k chunks for a query, expanded one hop over the graph.
+
+    Returns {chunks: [{source, text, score}], related: [entities]}.
+    """
+    chunks = index.get("chunks", [])
+    entities = index.get("entities", {})
+    edges = index.get("edges", {})
+    if not chunks:
+        return {"chunks": [], "related": []}
+
+    q_entities = set(extract_entities(query))
+    q_words = {w for w in (w.lower() for w in _RE_WORD.findall(query))
+               if len(w) > 2 and w not in _STOPWORDS}
+
+    # Match query entities to graph entities (exact + substring both ways).
+    matched: set[str] = set()
+    for qe in q_entities | q_words:
+        for ge in entities:
+            if qe == ge or qe in ge or ge in qe:
+                matched.add(ge)
+
+    # 1-hop graph expansion: pull the strongest neighbors of matched entities.
+    related: list[str] = []
+    expanded: set[str] = set(matched)
+    if hops:
+        for e in list(matched):
+            nbrs = sorted(edges.get(e, {}).items(), key=lambda kv: -kv[1])[:5]
+            for nbr, _w in nbrs:
+                expanded.add(nbr)
+                if nbr not in matched:
+                    related.append(nbr)
+
+    # Score chunks: direct entity hits weigh most, then graph-neighbor hits,
+    # then raw keyword overlap (so retrieval still works if entities miss).
+    scores: dict[int, float] = defaultdict(float)
+    for e in matched:
+        for cid in entities.get(e, []):
+            scores[cid] += 3.0
+    for e in expanded - matched:
+        for cid in entities.get(e, []):
+            scores[cid] += 1.0
+    for c in chunks:
+        if q_words:
+            overlap = len(q_words & {w.lower() for w in _RE_WORD.findall(c["text"])})
+            if overlap:
+                scores[c["id"]] += 0.5 * overlap
+
+    ranked = sorted(scores.items(), key=lambda kv: -kv[1])[:k]
+    out_chunks = [
+        {"source": chunks[cid]["source"], "text": chunks[cid]["text"], "score": round(sc, 1)}
+        for cid, sc in ranked if sc > 0
+    ]
+    # de-dup related, keep order, cap
+    seen: set[str] = set()
+    rel_unique = [r for r in related if not (r in seen or seen.add(r))][:12]
+    return {"chunks": out_chunks, "related": rel_unique}
+
+
+def format_results(result: dict, query: str) -> str:
+    """Render query results as the tool's string output for the model."""
+    chunks = result.get("chunks", [])
+    if not chunks:
+        return (
+            f"No knowledge-base matches for: {query!r}. The index may not cover "
+            "this topic — answer from your own knowledge, or ask the user to add "
+            "the relevant docs with /graphrag build <path>."
+        )
+    parts = [f"Knowledge base — {len(chunks)} relevant passage(s) for {query!r}:"]
+    for i, c in enumerate(chunks, 1):
+        parts.append(f"\n[{i}] (source: {c['source']}, score {c['score']})\n{c['text']}")
+    if result.get("related"):
+        parts.append("\nRelated entities in the graph: " + ", ".join(result["related"]))
+    return "\n".join(parts)

{drydock_cli-3.0.46 → drydock_cli-3.0.49}/drydock/loop_detect.py

@@ -86,6 +86,49 @@ def path_thrash_note(path: str, count: int) -> str | None:
     )
 
 
+def runaway_repetition_len(
+    text: str,
+    *,
+    window: int = 2000,
+    min_run: int = 600,
+    max_unit: int = 80,
+    min_reps: int = 6,
+) -> int:
+    """Length (in chars) of a runaway repeated SUFFIX of *text*, else 0.
+
+    A weak local model sometimes collapses mid-generation into emitting the same
+    short unit hundreds of times (observed: gemma4 streamed ``295:`` ~1365× on
+    make-mips-interpreter). The tool-call loop guard never sees this — it's
+    streamed assistant TEXT, not a tool call — so the turn balloons unchecked.
+
+    This detects that one failure mode and nothing else. It is deliberately
+    CONSERVATIVE: it requires a long pure-repetition run (>= ``min_run`` chars
+    AND >= ``min_reps`` repeats of one <= ``max_unit``-char unit) so that
+    legitimate repetition — a ``---`` rule, a short bulleted list, an ASCII
+    table — never trips it. Pure-whitespace units (the blank line between
+    markdown blocks) are ignored. Returns the run length so the caller can trim
+    exactly the repeated tail; 0 means "looks fine, keep going".
+    """
+    if len(text) < min_run:
+        return 0
+    tail = text[-window:]
+    n = len(tail)
+    best = 0
+    for p in range(1, min(max_unit, n // min_reps) + 1):
+        unit = tail[-p:]
+        if not unit.strip():
+            continue  # ignore blank-line / whitespace units
+        reps = 0
+        i = n
+        while i - p >= 0 and tail[i - p:i] == unit:
+            reps += 1
+            i -= p
+        run = reps * p
+        if reps >= min_reps and run >= min_run:
+            best = max(best, run)
+    return best
+
+
 class LoopTracker:
     """Counts identical tool calls across a run and produces advisory notes."""
 

{drydock_cli-3.0.46 → drydock_cli-3.0.49}/drydock/providers.py

@@ -23,7 +23,8 @@ _LLM_POOL = concurrent.futures.ThreadPoolExecutor(max_workers=8, thread_name_pre
 class _StopRequested(Exception):
     """Internal: STOP was pressed during a blocking LLM call."""
 
-from drydock.tuning import strip_leaked_tool_calls, strip_thinking_tokens, use_streaming
+from drydock.loop_detect import runaway_repetition_len
+from drydock.tuning import extract_thinking, strip_leaked_tool_calls, strip_thinking_tokens, use_streaming
 
 # ── Provider registry ─────────────────────────────────────────────────────
 
@@ -167,6 +168,14 @@ def _stream_chunks(response, cancel):
 class TextChunk:
     text: str
 
+@dataclass
+class ReasoningChunk:
+    """Thinking tokens emitted by the model before its answer (Gemma 4 only).
+    Yielded once per non-streaming turn, before any TextChunk, when the model
+    included a <|channel>…<channel|> block in its response.
+    """
+    text: str
+
 @dataclass
 class AssistantTurn:
     text: str
@@ -405,6 +414,11 @@ def stream(
     text = ""
     tool_buf: dict = {}  # index → {id, name, args}
     in_tok = out_tok = 0
+    # Runaway-repetition guard: a weak model can collapse into streaming one
+    # short unit hundreds of times (gemma4: `295:` ×1365). Advisory, never
+    # raises — on detection we trim the repeated tail, emit a note, and stop
+    # reading (the orphaned producer drains in the background, like STOP).
+    _rep_checked_at = 0
 
     try:
         response = _create_abortable(client, kwargs, base_url, provider, cancel, read_timeout)
@@ -432,6 +446,20 @@ def stream(
             if chunk_text:
                 text += chunk_text
                 yield TextChunk(chunk_text)
+                # Throttled: only scan once text is long enough and every ~200
+                # new chars, so the common path pays almost nothing.
+                if len(text) - _rep_checked_at >= 200:
+                    _rep_checked_at = len(text)
+                    run = runaway_repetition_len(text)
+                    if run:
+                        text = (
+                            text[: len(text) - run]
+                            + "\n[… output began repeating — stopped by drydock]"
+                        )
+                        yield TextChunk(
+                            "\n[stopped — model output began repeating itself]"
+                        )
+                        break
 
         if delta.tool_calls:
             for tc in delta.tool_calls:
@@ -479,10 +507,12 @@ def _complete_nonstreaming(
     msg = choice.message
 
     # Order matters: remove <|tool_call> blobs FIRST (sets had_leak for the
-    # retry nudge), THEN strip channel/special-token markers — otherwise the
-    # generic special-token pass would eat the tool_call markers.
+    # retry nudge), THEN extract+strip channel/special-token markers — otherwise
+    # the generic special-token pass would eat the tool_call markers.
     text, had_leak = strip_leaked_tool_calls(msg.content or "")
-    text = strip_thinking_tokens(text)
+    thinking, text = extract_thinking(text)
+    if thinking:
+        yield ReasoningChunk(thinking)
     if text.strip():
         yield TextChunk(text)
 

{drydock_cli-3.0.46 → drydock_cli-3.0.49}/drydock/tools/__init__.py

@@ -161,6 +161,32 @@ SCHEMAS = [
             "required": ["prompt"],
         },
     },
+    {
+        "name": "Knowledge",
+        "description": (
+            "Search the user's KNOWLEDGE BASE (a GraphRAG index they built from "
+            "their own docs/code) for project-specific information you were not "
+            "trained on. Returns the most relevant passages plus related entities "
+            "from the graph. Use it BEFORE answering or coding when the task may "
+            "depend on the user's private/project knowledge (their APIs, specs, "
+            "data, conventions). If it returns no matches, the topic isn't in the "
+            "base — answer normally."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "What to look up, as a natural-language question or keywords.",
+                },
+                "k": {
+                    "type": "integer",
+                    "description": "Max passages to return (default 5).",
+                },
+            },
+            "required": ["query"],
+        },
+    },
 ]
 
 # ── Tool implementations ──────────────────────────────────────────────────
@@ -709,6 +735,32 @@ def tool_task(params: dict, config: dict) -> str:
     return f"[sub-agent finished {steps} step(s) with no summary]"
 
 
+def tool_knowledge(params: dict, config: dict) -> str:
+    """Query the project's GraphRAG knowledge base (built with /graphrag build).
+    Read-only; returns the most relevant passages plus related graph entities.
+    If no index exists, says so cleanly rather than erroring."""
+    from drydock import graphrag
+
+    query = (params.get("query") or "").strip()
+    if not query:
+        return "Error: `Knowledge` needs a `query` describing what to look up."
+    cwd = config.get("cwd") or os.getcwd()
+    store = config.get("graphrag_store") or graphrag.default_store_path(cwd)
+    index = graphrag.load_index(store)
+    if index is None:
+        return (
+            "No knowledge base has been built yet. The user can build one with "
+            "'/graphrag build <path>' (a file or directory of docs/code). Until "
+            "then, answer from your own knowledge."
+        )
+    try:
+        k = int(params.get("k") or 5)
+    except (TypeError, ValueError):
+        k = 5
+    result = graphrag.query_index(index, query, k=max(1, min(k, 15)))
+    return graphrag.format_results(result, query)
+
+
 # ── Register all tools ────────────────────────────────────────────────────
 
 _TOOLS = [
@@ -720,6 +772,7 @@ _TOOLS = [
     ("Grep", tool_grep, True),
     ("todo", tool_todo, False),
     ("task", tool_task, True),
+    ("Knowledge", tool_knowledge, True),
 ]
 
 def register_all():
@@ -728,10 +781,10 @@ def register_all():
         func = {
             "Read": tool_read, "Write": tool_write, "Edit": tool_edit,
             "Bash": tool_bash, "Glob": tool_glob, "Grep": tool_grep,
-            "todo": tool_todo, "task": tool_task,
+            "todo": tool_todo, "task": tool_task, "Knowledge": tool_knowledge,
         }[name]
-        # `task` is read-only w.r.t. the parent's files (it can't Write/Edit).
-        read_only = name in ("Read", "Glob", "Grep", "task")
+        # task + Knowledge are read-only w.r.t. the parent's files.
+        read_only = name in ("Read", "Glob", "Grep", "task", "Knowledge")
         register(ToolDef(name=name, schema=schema, func=func, read_only=read_only))
 
 register_all()