drydock-cli 3.1.23__tar.gz → 3.1.27__tar.gz

{drydock_cli-3.1.23/drydock_cli.egg-info → drydock_cli-3.1.27}/PKG-INFO

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

{drydock_cli-3.1.23 → drydock_cli-3.1.27}/drydock/agent.py

@@ -107,6 +107,8 @@ class AgentState:
     events: "EventLog | SQLiteEventLog | None" = None  # optional durable execution trace
     recovery_stage: int = 0  # live recovery escalation stage (0 = normal); for the TUI
     progress_streak: int = 0  # consecutive no-progress (stall) actions; for the TUI
+    verify_fail_streak: int = 0  # consecutive FAILING checks; drives the /ratchet offer
+    last_verify_cmd: str = ""    # the command behind that streak (pre-fills the offer)
     budget: "BudgetState" = field(default_factory=lambda: BudgetState())  # scoped budgets
 
 
@@ -308,12 +310,24 @@ def run(
                 # relevant to this task + phase, capped at max_tools (default 12).
                 # Trims nothing when already under the cap; core coding tools are
                 # never dropped.
+                # Pin Knowledge when the project HAS a GraphRAG index. Its purpose
+                # is to answer plain questions from the user's own corpus, but the
+                # keyword gate only fires on knowledge/graph/entity/graphrag/ingest
+                # — words a user asking "what does the auth module do?" never types
+                # — so it was trimmed and the call came back "not available here".
+                _pins = list(turn_config.get("pin_tools") or [])
+                try:
+                    from drydock.graphrag import knowledge_base_exists
+                    if "Knowledge" not in _pins and knowledge_base_exists(os.getcwd()):
+                        _pins.append("Knowledge")
+                except Exception:
+                    pass          # advisory: never let this break the turn
                 available = select_tools(
                     available,
                     phase=str(state.task.phase),
                     task_text=state.task.objective,
                     max_tools=turn_config.get("max_tools", DEFAULT_MAX_TOOLS),
-                    pin_tools=turn_config.get("pin_tools") or [],
+                    pin_tools=_pins,
                 )
                 for event in stream(
                     model=turn_config["model"],
@@ -745,6 +759,16 @@ def run(
                 _vcmd = (tc.get("input") or {}).get("command", "")
                 if looks_like_verification(_vcmd):
                     last_verification = parse_evidence(_vcmd, result)
+                    # Streak of consecutive FAILING checks, for the TUI's proactive
+                    # /ratchet offer (ratchet.ratchet_offer). Reset on any pass, so it
+                    # only fires while the model is genuinely stuck re-running the same
+                    # check — which is precisely the ratchet's use case. Advisory: this
+                    # counter never changes the agent's own behaviour.
+                    if last_verification.status == "fail":
+                        state.verify_fail_streak += 1
+                        state.last_verify_cmd = _vcmd
+                    elif last_verification.status == "pass":
+                        state.verify_fail_streak = 0
                     # Accumulate what the checks touched (command + result text),
                     # capped, for criteria-coverage at completion time.
                     if len(verification_text) < 200_000:

drydock_cli-3.1.27/drydock/bottleneck.py

@@ -0,0 +1,218 @@
+"""Bottleneck register — after a system is decomposed, rank its KNOWN components by
+how much the objective actually moves if you improve each one, and attack the one
+limiting factor instead of optimising everything evenly.
+
+WHY THIS IS A SEPARATE STEP FROM THE LEDGER
+-------------------------------------------
+`groundtruth.py` ranks UNKNOWNS by decision impact — it answers "what don't I know
+that could change the plan?" That is an epistemic question. The bottleneck is a
+different question, and conflating the two loses it: the limiting factor is usually
+something you already KNOW with no uncertainty at all. You can be perfectly certain
+which stage is slowest and still pour effort into a faster one.
+
+This project is its own evidence. Two of its largest course-corrections were bottleneck
+findings, not discoveries:
+  · "throughput is the master lever" — the search was being made cleverer for weeks while
+    the objective barely moved, because the limiting factor was how many traces the box
+    could produce per hour, not how good each one was.
+  · "the real lever is training solves back into the model (write-back), not fancier
+    search" — the same shape a second time: effort concentrated on a component with lots
+    of headroom but little SHARE of the objective, while the component with the share sat
+    untouched.
+Neither of those was an unknown. `next_test()` would not have surfaced either, because
+there was nothing to learn — only a limiting factor to name and attack.
+
+THE ONE NUMBER IT COMPUTES
+--------------------------
+For a component that controls a fraction `share` of the objective's gap and still has a
+fraction `headroom` left to improve, the realizable gain from perfecting it is
+`share * headroom`. The bottleneck is the component with the largest realizable gain —
+NOT the one that is easiest to improve (high headroom, low share: the trap this whole
+module exists to name), and NOT the biggest cost that happens to be a fundamental
+constraint you cannot move (high share, zero headroom: a wall, not a lever).
+
+The Amdahl ceiling `share` is reported alongside: it is the most that component could
+EVER buy you, even with an infinitely good improvement. A lever with a 5% ceiling is
+capped at 5% no matter how brilliant the optimisation — that ceiling is the sentence
+that ends most premature-optimisation arguments.
+
+WHY THIS IS NOT A PROMPT
+Same reason as the other two modules: a reasoning checklist telling the model to "find
+the bottleneck first" was measured on terminal-bench-2 and lost to a plain retry. This
+gives the model somewhere to put the decomposition and computes the one comparison it is
+bad at doing in its head — the share×headroom product across a handful of components.
+
+Advisory by contract: nothing here raises on bad input, blocks a call, or edits a plan.
+It records, ranks, and renders. See also `groundtruth.py` and `predictions.py`.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+# A component is a "wall" (fundamental constraint, not a lever) once its headroom is
+# this low: no realistic optimisation moves it, so naming it stops you re-attacking it.
+_WALL_HEADROOM = 0.05
+
+
+def _clamp01(x: object, default: float = 0.0) -> float:
+    try:
+        v = float(x)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return default
+    if v != v:  # NaN
+        return default
+    return 0.0 if v < 0.0 else 1.0 if v > 1.0 else v
+
+
+@dataclass
+class Component:
+    """One piece of the decomposed system, and its two numbers that matter."""
+    id: str
+    name: str = ""
+    # Fraction of the objective's gap this component controls (its Amdahl share). If the
+    # objective is end-to-end latency and this stage is 70% of it, share = 0.7. This is a
+    # SENSITIVITY, not the effort currently spent on it — the whole point is that the two
+    # come apart.
+    share: float = 0.0
+    # Fraction of THIS component still improvable. 0 = a fundamental constraint (physics,
+    # a hard resource limit, already optimal) you cannot move; 1 = could be eliminated
+    # entirely. This is where step 4 (fundamental constraints) enters the arithmetic.
+    headroom: float = 1.0
+    note: str = ""
+
+    def gain(self) -> float:
+        """Realizable objective gain from exploiting this component's headroom."""
+        return self.share * self.headroom
+
+    def ceiling(self) -> float:
+        """Amdahl ceiling: the most this component could EVER buy, headroom aside."""
+        return self.share
+
+    def is_wall(self) -> bool:
+        return self.share > 0 and self.headroom <= _WALL_HEADROOM
+
+    def summary(self) -> str:
+        mark = "▮" if self.is_wall() else "▲"
+        return (f"{mark} {self.id} {self.name[:56]} "
+                f"[gain {self.gain():.0%} · ceiling {self.ceiling():.0%} · "
+                f"headroom {self.headroom:.0%}]")
+
+
+class Bottlenecks:
+    """The decomposed components of one problem, persisted next to the run."""
+
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path) if path else None
+        self.items: list[Component] = []
+        if self.path and self.path.exists():
+            self.load()
+
+    # ── recording ────────────────────────────────────────────────────────────
+    def add(self, name: str, *, share: float = 0.0, headroom: float = 1.0,
+            note: str = "") -> Component:
+        """Record a decomposed component. Out-of-range numbers are clamped to [0,1]
+        rather than raising — a register that throws would take down the turn it is
+        meant to help."""
+        c = Component(id=f"c{len(self.items) + 1}",
+                      name=(name or "").strip(),
+                      share=_clamp01(share, 0.0),
+                      headroom=_clamp01(headroom, 1.0),
+                      note=(note or "").strip())
+        self.items.append(c)
+        self._save()
+        return c
+
+    def update(self, cid: str, *, share: float | None = None,
+               headroom: float | None = None, note: str | None = None) -> Component | None:
+        """Revise a component's numbers as measurement replaces estimate. Attacking the
+        bottleneck moves its headroom toward 0, at which point the ranking shifts to the
+        next limiting factor on its own."""
+        for c in self.items:
+            if c.id == cid:
+                if share is not None:
+                    c.share = _clamp01(share, c.share)
+                if headroom is not None:
+                    c.headroom = _clamp01(headroom, c.headroom)
+                if note is not None:
+                    c.note = (note or "").strip()
+                self._save()
+                return c
+        return None
+
+    # ── the ranking that is the point of the module ──────────────────────────
+    def _levers(self) -> list[Component]:
+        """Components that are actually worth attacking — positive gain and not a wall.
+        A wall's sliver of headroom is not a lever, so it is excluded here even though its
+        gain is technically > 0."""
+        return [c for c in self.items if c.gain() > 0 and not c.is_wall()]
+
+    def bottleneck(self) -> Component | None:
+        """The one limiting factor to attack first: the largest realizable gain
+        (share × headroom). Ties break toward the larger share — the higher ceiling is
+        the safer bet once the immediate gain is equal."""
+        movable = self._levers()
+        if not movable:
+            return None
+        return sorted(movable, key=lambda c: (-c.gain(), -c.share, c.id))[0]
+
+    def ranked(self) -> list[Component]:
+        return sorted(self.items, key=lambda c: (-c.gain(), -c.share, c.id))
+
+    def walls(self) -> list[Component]:
+        """High-share components with (almost) no headroom — fundamental constraints.
+        Naming them is what stops the loop re-attacking a wall as if it were a lever."""
+        return [c for c in self.items if c.is_wall()]
+
+    def misplaced_effort(self) -> Component | None:
+        """The trap this module exists to catch: the component with the MOST headroom is
+        not the bottleneck — improving it feels productive but is capped by its small
+        share. Returns that decoy when it differs from the real bottleneck, else None."""
+        movable = self._levers()
+        if len(movable) < 2:
+            return None
+        by_headroom = max(movable, key=lambda c: (c.headroom, -c.share))
+        bn = self.bottleneck()
+        return by_headroom if bn is not None and by_headroom.id != bn.id else None
+
+    # ── rendering ────────────────────────────────────────────────────────────
+    def render(self) -> str:
+        if not self.items:
+            return "(no components decomposed yet)"
+        lines = [c.summary() for c in self.ranked()]
+        bn = self.bottleneck()
+        if bn is not None:
+            lines.append(f"→ attack first: {bn.id} ({bn.name[:50]}) — "
+                         f"realizable gain {bn.gain():.0%}, ceiling {bn.ceiling():.0%}")
+        else:
+            lines.append("→ no movable component: every lever is a wall "
+                         "(headroom ~0). The objective may need a different decomposition.")
+        decoy = self.misplaced_effort()
+        if decoy is not None:
+            lines.append(f"⚠ {decoy.id} has the most headroom but only a "
+                         f"{decoy.ceiling():.0%} ceiling — optimising it is capped there.")
+        total_share = sum(c.share for c in self.items)
+        if total_share > 1.05:
+            lines.append(f"⚠ shares sum to {total_share:.0%} (>100%): the decomposition "
+                         "overlaps — components are not independent.")
+        return "\n".join(lines)
+
+    # ── persistence ──────────────────────────────────────────────────────────
+    def _save(self) -> None:
+        if not self.path:
+            return
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(
+                json.dumps([asdict(c) for c in self.items], indent=2), encoding="utf-8")
+        except OSError:
+            pass          # advisory: never fail a run over bookkeeping
+
+    def load(self) -> None:
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8")) if self.path else []
+            self.items = [Component(**{k: v for k, v in d.items()
+                                       if k in Component.__dataclass_fields__}) for d in raw]
+        except (OSError, json.JSONDecodeError, TypeError):
+            self.items = []

{drydock_cli-3.1.23 → drydock_cli-3.1.27}/drydock/cli.py

@@ -373,6 +373,16 @@ def main():
         cfg["cwd"] = os.getcwd()
         sys.exit(run_cli(sys.argv[2:], config=cfg))
 
+    # `drydock swarm <objective> …` / `swarm status|list|resume` — multi-agent swarm.
+    # Same argv-intercept pattern as eratchet so the subcommand parses its own flags.
+    if len(sys.argv) > 1 and sys.argv[1] == "swarm":
+        from drydock import config as cfgmod
+        from drydock.swarm import run_cli as swarm_run_cli
+        cfg = cfgmod.resolve({}, cfgmod.default_config_path())
+        cfgmod.resolve_active_model(cfg)
+        cfg["cwd"] = os.getcwd()
+        sys.exit(swarm_run_cli(sys.argv[2:], config=cfg))
+
     parser = argparse.ArgumentParser(description="DryDock — local coding agent")
     parser.add_argument(
         "--version", "-V", action="version", version=f"drydock {__version__}"

{drydock_cli-3.1.23 → drydock_cli-3.1.27}/drydock/config.py

@@ -40,6 +40,15 @@ DEFAULTS: dict[str, object] = {
     # generation usually isn't stalled — a known gemma/llama.cpp hang). 0 = off.
     # Set to e.g. 600 on a stall-prone local server. Bounded to a few retries.
     "stall_retry_secs": 0,
+    # Idle-output watchdog for foreground Bash: if a running command produces NO
+    # output for this many seconds, drydock stops BLOCKING on it and adopts it as a
+    # background job (it keeps running; the agent gets the prompt back + a nudge to
+    # reconsider). Complements the total-runtime auto-background (_AUTO_BG_TIMEOUT):
+    # catches a command hung SILENTLY on a long timeout (e.g. a dead network
+    # download the model set timeout:1800 for) far sooner than the total cap.
+    # Non-destructive (backgrounds, never kills). 0 = off. Set e.g. 300 on the fleet
+    # where a weak local model loops on a silently-stuck command.
+    "bash_idle_bg_secs": 0,
     # Inject bundled technique recipes (drydock/recipes.py) relevant to the task
     # into the system prompt, so a local model has the *method* a task needs
     # instead of guessing. Retrieval is keyword-overlap; only relevant recipes are
@@ -88,6 +97,11 @@ DEFAULTS: dict[str, object] = {
     # web tools surfaced even on tasks whose text never mentions the web. Names
     # not in the registry are ignored.
     "pin_tools": [],
+    # When a single agent stays stuck on a KNOWN verifier (it keeps failing), the harness
+    # may auto-escalate to an in-process multi-agent swarm to explore approaches in parallel
+    # (docs/multi_agent_swarm_prd.md). On by default; set false to keep every request single-
+    # agent unless the user runs /swarm explicitly.
+    "swarm_auto_escalate": True,
     # URL substrings the web tools refuse: WebSearch drops matching results,
     # WebFetch declines matching URLs (with a plain message, never an error).
     # Used to keep benchmark/solution sites out of harvested training runs.

{drydock_cli-3.1.23 → drydock_cli-3.1.27}/drydock/graphrag.py

@@ -65,6 +65,26 @@ def default_store_path(cwd: str) -> Path:
     return Path(cwd) / ".drydock" / "graphrag.db"
 
 
+def knowledge_base_exists(cwd: str) -> bool:
+    """True when this project has a built GraphRAG index (SQLite or legacy JSON).
+
+    Used to PIN the `Knowledge` tool for the turn. Dynamic tool selection
+    (tool_select) otherwise gates Knowledge behind the keywords
+    knowledge/graph/entity/graphrag/ingest, which the user has no reason to type:
+    the whole point of the feature is that a plain question like "what does the
+    auth module do?" is answered FROM their index. With 46 tools and a cap of 12,
+    that question dropped Knowledge from the toolset and the model's call came
+    back "[The 'Knowledge' tool is not available here]" — the bug reported
+    2026-09-03. Knowledge is read-only and cheap, so pinning it whenever an index
+    exists costs one slot and restores the documented behaviour; when no index
+    exists nothing is pinned and the tool stays gated as before.
+    """
+    try:
+        return _resolve_store(default_store_path(cwd)).exists()
+    except Exception:      # never let a tool-selection helper break the turn
+        return False
+
+
 def _resolve_store(store_path) -> Path:
     """Given a requested store path, return the one that actually exists — a
     ``.db`` (SQLite) if present, else a legacy ``.json`` sibling, else the path

drydock_cli-3.1.27/drydock/groundtruth.py

@@ -0,0 +1,167 @@
+"""Ground-truth ledger — separate what is KNOWN from what is ASSUMED, and rank the
+unknowns by how much they could change the decision.
+
+WHY THIS EXISTS, and why it is a LEDGER rather than a prompt
+------------------------------------------------------------
+A reasoning checklist was measured on terminal-bench-2 and did not work: applied to
+every task it caused regressions (it overthinks work that was already succeeding), and
+applied only after a failure it was BEATEN by simply retrying (4.6%/4.7% rescue vs a
+plain retry's 6.2%). A longer ten-step variant did worse than a short one, and
+compliance explained why — the long form was followed less often (criteria written 3/8
+vs 7/8). More instructions bought less behaviour.
+
+So this module deliberately does NOT tell the model how to think. It gives it somewhere
+to PUT things, and it computes one ranking the model is bad at doing in its head.
+
+The specific thing it computes — `next_test()` — comes from a failure in this project's
+own research log rather than from theory. A claim about a prompt scaffold was reported
+at +6.8 points, corrected to +3.4, then to +0.0. Every correction came from a control
+that could have been run on day one; the highest-value unknown was always "would a plain
+retry do the same thing?", and it went unasked for six days while cheaper, less
+decisive experiments ran. Ranking unknowns by DECISION IMPACT (not by how interesting or
+how easy they are) is the step that would have caught it immediately.
+
+Advisory by contract: nothing here blocks a tool call, raises on bad input, or edits the
+model's plan. It records, ranks, and renders. See also `predictions.py`, which closes the
+other half of the loop (predict before you look).
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+# Confidence bands. Kept coarse on purpose: a model asked for a 0-100 confidence emits
+# noise, but "did I VERIFY this or am I assuming it" is a distinction it can actually make.
+FACT = "fact"            # verified by looking (a file read, a command's output)
+ASSUMPTION = "assumption"  # believed, not checked — the usual source of a stuck run
+UNKNOWN = "unknown"        # explicitly not known
+KINDS = (FACT, ASSUMPTION, UNKNOWN)
+
+
+@dataclass
+class Item:
+    """One thing believed about the problem, and where that belief came from."""
+    id: str
+    kind: str = ASSUMPTION
+    statement: str = ""
+    # For FACT: how it was verified (the command, the file). Empty evidence on a FACT is
+    # itself a smell — it means something got promoted without being checked.
+    evidence: str = ""
+    # For ASSUMPTION/UNKNOWN: how much the decision changes if this turns out false.
+    # 0 = irrelevant, 3 = the approach is invalid. This is the field that does the work.
+    impact: int = 0
+    # Rough cost to find out (0 = seconds, 3 = hours). Used only to break impact ties, so
+    # a cheap decisive test wins over an expensive one — never to avoid a decisive test.
+    cost: int = 1
+    resolved: bool = False
+
+    def summary(self) -> str:
+        mark = {FACT: "✓", ASSUMPTION: "?", UNKNOWN: "·"}.get(self.kind, "·")
+        if self.resolved:
+            mark = "✔"
+        tag = f" [impact {self.impact}/cost {self.cost}]" if self.kind != FACT else ""
+        return f"{mark} {self.id} {self.statement[:70]}{tag}"
+
+
+class Ledger:
+    """Facts, assumptions and unknowns for one task, persisted next to the run."""
+
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path) if path else None
+        self.items: list[Item] = []
+        if self.path and self.path.exists():
+            self.load()
+
+    # ── recording ────────────────────────────────────────────────────────────
+    def add(self, statement: str, kind: str = ASSUMPTION, *, evidence: str = "",
+            impact: int = 0, cost: int = 1) -> Item:
+        """Record a belief. Unknown kinds degrade to ASSUMPTION rather than raising —
+        a ledger that throws would take down the turn it is supposed to be helping."""
+        if kind not in KINDS:
+            kind = ASSUMPTION
+        it = Item(id=f"i{len(self.items) + 1}", kind=kind,
+                  statement=(statement or "").strip(),
+                  evidence=(evidence or "").strip(),
+                  impact=max(0, min(3, int(impact or 0))),
+                  cost=max(0, min(3, int(cost or 1))))
+        self.items.append(it)
+        self._save()
+        return it
+
+    def verify(self, item_id: str, evidence: str) -> Item | None:
+        """Promote an assumption to a fact, with the evidence that earned it. This is the
+        only path to FACT — a belief cannot become a fact by being restated."""
+        for it in self.items:
+            if it.id == item_id:
+                it.kind = FACT
+                it.evidence = (evidence or "").strip()
+                it.resolved = True
+                self._save()
+                return it
+        return None
+
+    def refute(self, item_id: str, evidence: str) -> Item | None:
+        """Mark an assumption FALSE. Kept rather than deleted: a refuted assumption is
+        the most valuable row in the ledger — it is the one that changed the approach."""
+        for it in self.items:
+            if it.id == item_id:
+                it.statement = f"[REFUTED] {it.statement}"
+                it.kind = FACT
+                it.evidence = (evidence or "").strip()
+                it.resolved = True
+                self._save()
+                return it
+        return None
+
+    # ── the ranking that is the point of the module ──────────────────────────
+    def open_uncertainties(self) -> list[Item]:
+        return [i for i in self.items if not i.resolved and i.kind != FACT]
+
+    def next_test(self) -> Item | None:
+        """The unknown worth attacking first: highest decision-impact, cheapest to settle
+        among equals. NOT the easiest, and NOT the most interesting — those are the two
+        attractors that let a project run six days of experiments that could not have
+        changed its own conclusion."""
+        openq = [i for i in self.open_uncertainties() if i.impact > 0]
+        if not openq:
+            return None
+        return sorted(openq, key=lambda i: (-i.impact, i.cost, i.id))[0]
+
+    def unevidenced_facts(self) -> list[Item]:
+        """FACTs carrying no evidence — i.e. assumptions wearing a fact's badge."""
+        return [i for i in self.items if i.kind == FACT and not i.evidence]
+
+    # ── rendering ────────────────────────────────────────────────────────────
+    def render(self) -> str:
+        if not self.items:
+            return "(ledger empty)"
+        lines = [i.summary() for i in self.items]
+        nxt = self.next_test()
+        if nxt:
+            lines.append(f"→ test first: {nxt.id} ({nxt.statement[:60]}) "
+                         f"— impact {nxt.impact}, cost {nxt.cost}")
+        stale = self.unevidenced_facts()
+        if stale:
+            lines.append(f"⚠ {len(stale)} 'fact(s)' with no evidence: "
+                         f"{', '.join(i.id for i in stale)}")
+        return "\n".join(lines)
+
+    # ── persistence ──────────────────────────────────────────────────────────
+    def _save(self) -> None:
+        if not self.path:
+            return
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(
+                json.dumps([asdict(i) for i in self.items], indent=2), encoding="utf-8")
+        except OSError:
+            pass          # advisory: never fail a run over bookkeeping
+
+    def load(self) -> None:
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8")) if self.path else []
+            self.items = [Item(**{k: v for k, v in d.items()
+                                  if k in Item.__dataclass_fields__}) for d in raw]
+        except (OSError, json.JSONDecodeError, TypeError):
+            self.items = []