drydock-cli 3.1.14__tar.gz → 3.1.16__tar.gz

{drydock_cli-3.1.14/drydock_cli.egg-info → drydock_cli-3.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 3.1.14
+Version: 3.1.16
 Summary: Drydock — a local, provider-agnostic terminal coding agent for local LLMs
 Author: Frank Bobe III
 License-Expression: Apache-2.0
@@ -13,6 +13,9 @@ License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: openai>=1.0
 Requires-Dist: textual>=0.80
+Requires-Dist: httpx>=0.23
+Requires-Dist: rich>=13.0
+Requires-Dist: pypdf>=3.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-timeout; extra == "dev"
@@ -350,6 +353,12 @@ pip install drydock-cli
 drydock
 ```
 
+> ⚠️ **The PyPI package is `drydock-cli`, not `drydock`.** `pip install drydock`
+> fetches an unrelated project (a Docker-cluster tool) that ships its own
+> `drydock/` package with no `cli.py`, so the `drydock` command then fails with
+> `No module named 'drydock.cli'`. If that happened, run
+> `pip uninstall -y drydock drydock-cli && pip install drydock-cli`.
+
 Requires Python 3.11+. From source instead:
 `git clone https://github.com/fbobe321/drydock.git && cd drydock && pip install -e .`
 

{drydock_cli-3.1.14 → drydock_cli-3.1.16}/README.md

@@ -326,6 +326,12 @@ pip install drydock-cli
 drydock
 ```
 
+> ⚠️ **The PyPI package is `drydock-cli`, not `drydock`.** `pip install drydock`
+> fetches an unrelated project (a Docker-cluster tool) that ships its own
+> `drydock/` package with no `cli.py`, so the `drydock` command then fails with
+> `No module named 'drydock.cli'`. If that happened, run
+> `pip uninstall -y drydock drydock-cli && pip install drydock-cli`.
+
 Requires Python 3.11+. From source instead:
 `git clone https://github.com/fbobe321/drydock.git && cd drydock && pip install -e .`
 

drydock_cli-3.1.16/drydock/comms/__init__.py

@@ -0,0 +1,58 @@
+"""Drydock Comms — the communication layer (PRD): decide what the human needs to
+know, and how to tell them, separately from the agent's raw output.
+
+Public API (PRD §28):
+    from drydock import comms
+    comms.emit_event("decision.required", severity=comms.Severity.APPROVAL_REQUIRED,
+                     summary="Preserve the old API, or simplify and update callers?",
+                     requires_response=True, task_id="passkeys")
+
+emit_event runs the deterministic AttentionPolicy and routes to a channel; it
+returns the Decision. Comms failures never raise into the caller.
+"""
+from __future__ import annotations
+
+from .events import Decision, Event, Presence, Severity, NON_SUPPRESSIBLE
+from .attention import AttentionPolicy, AttentionConfig
+from .channels import Delivery, TelegramProvider, LogChannel
+
+_policy = AttentionPolicy()
+_delivery = Delivery()
+_presence = Presence.UNKNOWN
+
+
+def configure(policy: AttentionPolicy | None = None,
+              delivery: Delivery | None = None) -> None:
+    global _policy, _delivery
+    if policy is not None:
+        _policy = policy
+    if delivery is not None:
+        _delivery = delivery
+
+
+def set_presence(p: Presence) -> None:
+    global _presence
+    _presence = p
+
+
+def emit_event(type: str, severity: Severity = Severity.INFORMATIONAL,
+               summary: str = "", details: str = "", requires_response: bool = False,
+               interruptibility: str = "normal", source: str = "agent",
+               task_id: str = "") -> Decision:
+    """Offer an event to the comms layer; returns where it went. Never raises."""
+    try:
+        e = Event(type=type, severity=severity, summary=summary, details=details,
+                  requires_response=requires_response, interruptibility=interruptibility,
+                  source=source, task_id=task_id)
+        decision = _policy.decide(e, _presence)
+        _delivery.deliver(e, decision)
+        return decision
+    except Exception:  # noqa: BLE001 — a broken comms layer must not break the task
+        return Decision.LOG
+
+
+__all__ = [
+    "Decision", "Event", "Presence", "Severity", "NON_SUPPRESSIBLE",
+    "AttentionPolicy", "AttentionConfig", "Delivery", "TelegramProvider",
+    "LogChannel", "emit_event", "configure", "set_presence",
+]

drydock_cli-3.1.16/drydock/comms/attention.py

@@ -0,0 +1,120 @@
+"""Drydock Comms — the Attention Manager (PRD §6/§7/§25).
+
+A DELIBERATELY DETERMINISTIC policy: event + context → Decision. No LLM in the
+hot path (that would be latency, cost, and GPU contention with the coding model,
+and it would make 'why did it stay silent?' untestable). An LLM is used only to
+*word* the summary and to adjudicate the ambiguous mid-band — callers layer that
+on top; this module decides the CHANNEL.
+
+Guarantees (asserted in tests):
+  * Non-suppressible severities never fall below MESSAGE, regardless of cooldown,
+    presence (except DND still delivers), or dedup.
+  * Routine, low-severity, non-response events default to LOG/IGNORE.
+  * Repeated identical events are aggregated, not re-fired, until an escalation
+    threshold — then a single 'still happening' notice, once per escalation.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from .events import Decision, Event, Presence, Severity
+
+
+@dataclass
+class AttentionConfig:
+    # score→channel thresholds (PRD §29). Score is 0..5.
+    speak_at: int = 3
+    message_at: int = 4
+    # anti-annoyance
+    cooldown_secs: float = 300.0          # per dedup-key silence window
+    escalate_after: int = 4               # Nth suppressed dup → one aggregated notice
+    max_notifies_per_hour: int = 20       # global circuit breaker
+
+
+@dataclass
+class _KeyState:
+    last_notified: float = 0.0
+    suppressed: int = 0                   # dups seen inside the cooldown window
+
+
+@dataclass
+class AttentionPolicy:
+    cfg: AttentionConfig = field(default_factory=AttentionConfig)
+    _keys: dict = field(default_factory=dict)
+    _notify_times: list = field(default_factory=list)   # for the hourly breaker
+
+    # ── scoring (0..5) ──────────────────────────────────────────────────────
+    def _score(self, e: Event) -> int:
+        s = int(e.severity)              # 0..4 baseline from the authority ladder
+        if e.requires_response:
+            s = max(s, int(Severity.APPROVAL_REQUIRED))
+        if e.type in ("agent.stuck", "error.blocking", "security.warning"):
+            s = max(s, 3)
+        if e.type in ("task.completed", "milestone.reached"):
+            s = max(s, 2)
+        if e.type in ("task.progress", "test.passed", "test.started"):
+            s = min(s, 1)
+        return max(0, min(5, s))
+
+    def _channel_for_score(self, score: int, presence: Presence) -> Decision:
+        if score >= self.cfg.message_at:
+            # loud enough to reach a human: voice if they're listening, else message
+            return Decision.SPEAK if presence == Presence.VOICE else Decision.MESSAGE
+        if score >= self.cfg.speak_at:
+            if presence == Presence.VOICE:
+                return Decision.SPEAK
+            if presence == Presence.ACTIVE:
+                return Decision.DISPLAY
+            return Decision.MESSAGE       # significant but user not at the box
+        if score >= 2:
+            return Decision.DISPLAY
+        if score >= 1:
+            return Decision.LOG
+        return Decision.IGNORE
+
+    def _hourly_ok(self, now: float) -> bool:
+        self._notify_times = [t for t in self._notify_times if now - t < 3600]
+        return len(self._notify_times) < self.cfg.max_notifies_per_hour
+
+    def decide(self, e: Event, presence: Presence = Presence.UNKNOWN,
+               now: float | None = None) -> Decision:
+        now = time.time() if now is None else now
+
+        # ── INVARIANT 1: non-suppressible severities always reach the human ──
+        # No cooldown/dedup/breaker/presence (except an explicit DND still gets a
+        # message — a blocking/approval/security event must not be lost).
+        if e.is_non_suppressible():
+            dec = Decision.SPEAK if presence == Presence.VOICE else Decision.MESSAGE
+            self._note_notify(e, now)
+            return dec
+
+        score = self._score(e)
+
+        # ── anti-annoyance: cooldown + dedup + aggregation ──────────────────
+        key = e.dedup_key()
+        st = self._keys.get(key)
+        if st and (now - st.last_notified) < self.cfg.cooldown_secs:
+            st.suppressed += 1
+            # escalate ONCE when repetition crosses the threshold (PRD §25)
+            if st.suppressed == self.cfg.escalate_after and score >= self.cfg.speak_at:
+                st.last_notified = now
+                return (Decision.MESSAGE if presence != Presence.ACTIVE
+                        else Decision.DISPLAY)
+            return Decision.LOG          # inside cooldown → quietly log the dup
+
+        dec = self._channel_for_score(score, presence)
+
+        # global circuit breaker for loud channels (never applies to invariant 1)
+        if dec >= Decision.MESSAGE and not self._hourly_ok(now):
+            dec = Decision.DISPLAY
+
+        if dec >= Decision.DISPLAY:
+            self._keys[key] = _KeyState(last_notified=now)
+            if dec >= Decision.MESSAGE:
+                self._note_notify(e, now)
+        return dec
+
+    def _note_notify(self, e: Event, now: float) -> None:
+        self._notify_times.append(now)
+        self._keys[e.dedup_key()] = _KeyState(last_notified=now)

drydock_cli-3.1.16/drydock/comms/channels.py

@@ -0,0 +1,97 @@
+"""Drydock Comms — channel delivery (PRD §15/§17). Routes a Decision to a place:
+LOG→file, DISPLAY→stdout/TUI, MESSAGE→messaging provider, SPEAK→TTS (stub).
+
+Providers are pluggable (MessageProvider.send). The Telegram provider is
+config-driven (token+chat via env or explicit args) so it works headless on the
+fleet and can't accidentally hard-depend on a cloud service.
+"""
+from __future__ import annotations
+
+import os
+import json
+import urllib.request
+import urllib.parse
+
+from .events import Decision, Event
+
+
+class MessageProvider:
+    def send(self, text: str) -> bool:  # pragma: no cover - interface
+        raise NotImplementedError
+
+
+class TelegramProvider(MessageProvider):
+    """Minimal, dependency-free Telegram sender (stdlib urllib). Reads token/chat
+    from args or env (DRYDOCK_TG_TOKEN / DRYDOCK_TG_CHAT)."""
+
+    def __init__(self, token: str | None = None, chat_id: str | None = None):
+        self.token = token or os.environ.get("DRYDOCK_TG_TOKEN", "")
+        self.chat_id = chat_id or os.environ.get("DRYDOCK_TG_CHAT", "")
+
+    def configured(self) -> bool:
+        return bool(self.token and self.chat_id)
+
+    def send(self, text: str) -> bool:
+        if not self.configured():
+            return False
+        url = f"https://api.telegram.org/bot{self.token}/sendMessage"
+        data = urllib.parse.urlencode({"chat_id": self.chat_id, "text": text}).encode()
+        try:
+            with urllib.request.urlopen(url, data=data, timeout=10) as r:
+                return r.status == 200
+        except Exception:  # noqa: BLE001 — comms failure must never crash the task
+            return False
+
+
+class LogChannel:
+    def __init__(self, path: str = "/tmp/drydock_comms.log"):
+        self.path = path
+
+    def write(self, event: Event, decision: Decision) -> None:
+        try:
+            with open(self.path, "a") as f:
+                f.write(json.dumps({
+                    "ts": event.ts, "decision": decision.name, "type": event.type,
+                    "sev": int(event.severity), "task": event.task_id,
+                    "summary": event.summary,
+                }) + "\n")
+        except Exception:  # noqa: BLE001
+            pass
+
+
+def format_for_human(event: Event) -> str:
+    """The text a human sees/hears. For non-suppressible events we deliver the
+    summary VERBATIM (no paraphrase that could change what's being authorized).
+    Callers may substitute an LLM-worded summary for LOW-severity events only."""
+    who = f"[{event.task_id}] " if event.task_id else ""
+    if event.requires_response:
+        return f"{who}{event.summary}".strip()
+    return f"{who}{event.summary}".strip()
+
+
+class Delivery:
+    """Executes a Decision. Returns True if it reached the intended channel."""
+    def __init__(self, message_provider: MessageProvider | None = None,
+                 log: LogChannel | None = None, display=print, speak=None):
+        self.message_provider = message_provider or TelegramProvider()
+        self.log = log or LogChannel()
+        self.display = display
+        self.speak = speak
+
+    def deliver(self, event: Event, decision: Decision) -> bool:
+        self.log.write(event, decision)          # everything is always logged
+        text = format_for_human(event)
+        if decision == Decision.IGNORE or decision == Decision.LOG:
+            return True
+        if decision == Decision.DISPLAY:
+            self.display(f"drydock: {text}")
+            return True
+        if decision == Decision.MESSAGE:
+            return self.message_provider.send(f"Drydock: {text}")
+        if decision == Decision.SPEAK:
+            if self.speak:
+                self.speak(text)
+                return True
+            # no TTS wired yet → fall back to message so it isn't lost
+            return self.message_provider.send(f"Drydock: {text}")
+        return False

drydock_cli-3.1.16/drydock/comms/events.py

@@ -0,0 +1,86 @@
+"""Drydock Comms — typed events (the communication interface, separate from the
+agent's raw output). See the Comms PRD §5/§24.
+
+Design invariants (enforced in attention.py, asserted in tests):
+  * Certain severities are NON-SUPPRESSIBLE — the attention policy can never
+    downgrade them to LOG/IGNORE, and their summary is delivered faithfully
+    (never paraphrased-away). Silence is never approval.
+  * Everything else defaults to LOG/IGNORE unless it earns a louder channel.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+
+class Severity(IntEnum):
+    """Human-authority ladder (PRD §24). Order matters: >= APPROVAL_REQUIRED is
+    non-suppressible."""
+    INFORMATIONAL = 0
+    ADVISORY = 1
+    APPROVAL_REQUIRED = 2
+    BLOCKING = 3
+    CRITICAL = 4
+
+
+# Severities the policy may NEVER suppress or downgrade below MESSAGE, and whose
+# summary must be delivered verbatim (no lossy LLM paraphrase changing meaning).
+NON_SUPPRESSIBLE = frozenset(
+    {Severity.APPROVAL_REQUIRED, Severity.BLOCKING, Severity.CRITICAL}
+)
+
+
+class Decision(IntEnum):
+    """Where an event ends up. IGNORE < LOG < DISPLAY < MESSAGE < SPEAK by
+    'loudness'; a non-suppressible event is floored at MESSAGE."""
+    IGNORE = 0
+    LOG = 1
+    DISPLAY = 2
+    MESSAGE = 3
+    SPEAK = 4
+
+
+class Presence(IntEnum):
+    UNKNOWN = 0
+    AWAY = 1
+    NEARBY = 2
+    ACTIVE = 3          # at the TUI
+    VOICE = 4           # in a live voice session
+    DO_NOT_DISTURB = 5
+
+
+# A small, stable event vocabulary. Not exhaustive — apps may emit others; the
+# policy keys off severity/requires_response, not the exact string.
+KNOWN_TYPES = frozenset({
+    "task.started", "task.progress", "task.completed",
+    "decision.required", "clarification.required", "permission.required",
+    "test.failed", "test.passed",
+    "error.recoverable", "error.blocking", "security.warning",
+    "agent.stuck", "agent.recovered", "milestone.reached",
+    "user.message",
+})
+
+
+@dataclass
+class Event:
+    """A structured piece of agent activity offered to the comms layer."""
+    type: str
+    severity: Severity = Severity.INFORMATIONAL
+    summary: str = ""
+    details: str = ""
+    requires_response: bool = False
+    interruptibility: str = "normal"      # "low" | "normal" | "high"
+    source: str = "agent"
+    task_id: str = ""
+    confidence: float = 1.0
+    ts: float = field(default_factory=time.time)
+
+    def dedup_key(self) -> str:
+        """Anti-annoyance key (PRD §25): same class + same task + same gist →
+        aggregate rather than re-notify. Excludes CRITICAL/approval (those are
+        never deduped away)."""
+        return f"{self.type}|{self.task_id}|{self.summary[:80]}"
+
+    def is_non_suppressible(self) -> bool:
+        return self.severity in NON_SUPPRESSIBLE

{drydock_cli-3.1.14 → drydock_cli-3.1.16/drydock_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 3.1.14
+Version: 3.1.16
 Summary: Drydock — a local, provider-agnostic terminal coding agent for local LLMs
 Author: Frank Bobe III
 License-Expression: Apache-2.0
@@ -13,6 +13,9 @@ License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: openai>=1.0
 Requires-Dist: textual>=0.80
+Requires-Dist: httpx>=0.23
+Requires-Dist: rich>=13.0
+Requires-Dist: pypdf>=3.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-timeout; extra == "dev"
@@ -350,6 +353,12 @@ pip install drydock-cli
 drydock
 ```
 
+> ⚠️ **The PyPI package is `drydock-cli`, not `drydock`.** `pip install drydock`
+> fetches an unrelated project (a Docker-cluster tool) that ships its own
+> `drydock/` package with no `cli.py`, so the `drydock` command then fails with
+> `No module named 'drydock.cli'`. If that happened, run
+> `pip uninstall -y drydock drydock-cli && pip install drydock-cli`.
+
 Requires Python 3.11+. From source instead:
 `git clone https://github.com/fbobe321/drydock.git && cd drydock && pip install -e .`
 

{drydock_cli-3.1.14 → drydock_cli-3.1.16}/drydock_cli.egg-info/SOURCES.txt

@@ -66,6 +66,10 @@ drydock/builtin_skills/rmf-poam.md
 drydock/builtin_skills/rmf-review.md
 drydock/builtin_skills/stig-assess.md
 drydock/builtin_skills/stig-remediate.md
+drydock/comms/__init__.py
+drydock/comms/attention.py
+drydock/comms/channels.py
+drydock/comms/events.py
 drydock/tools/__init__.py
 drydock/tui/__init__.py
 drydock/tui/app.py
@@ -96,6 +100,7 @@ tests/test_bash_timeout_param.py
 tests/test_budget.py
 tests/test_cci.py
 tests/test_cli_agents.py
+tests/test_comms.py
 tests/test_compact_command.py
 tests/test_compaction.py
 tests/test_config.py
@@ -104,6 +109,7 @@ tests/test_context_limit_config.py
 tests/test_context_limit_issue25.py
 tests/test_criteria_coverage.py
 tests/test_cycling_detection.py
+tests/test_declared_deps.py
 tests/test_degenerate_argument.py
 tests/test_detect.py
 tests/test_dispatch.py

{drydock_cli-3.1.14 → drydock_cli-3.1.16}/drydock_cli.egg-info/requires.txt

@@ -1,5 +1,8 @@
 openai>=1.0
 textual>=0.80
+httpx>=0.23
+rich>=13.0
+pypdf>=3.0
 
 [dev]
 pytest

{drydock_cli-3.1.14 → drydock_cli-3.1.16}/pyproject.toml

@@ -7,14 +7,24 @@ build-backend = "setuptools.build_meta"
 # PyPI distribution name is drydock-cli (the established install name, continued
 # from the retired v2 fork); the import package + CLI command stay `drydock`.
 name = "drydock-cli"
-version = "3.1.14"
+version = "3.1.16"
 description = "Drydock — a local, provider-agnostic terminal coding agent for local LLMs"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 authors = [{ name = "Frank Bobe III" }]
-dependencies = ["openai>=1.0", "textual>=0.80"]
+# Every package imported directly by drydock/ must be declared here — do NOT rely
+# on transitive deps (httpx via openai, rich via textual): a clean/partial install
+# then fails at runtime with ModuleNotFoundError (httpx bug, v3.1.15). pypdf is not
+# transitive at all, so PDF extraction silently broke on fresh installs.
+dependencies = [
+    "openai>=1.0",
+    "textual>=0.80",
+    "httpx>=0.23",
+    "rich>=13.0",
+    "pypdf>=3.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/fbobe321/drydock"

drydock_cli-3.1.16/tests/test_comms.py

@@ -0,0 +1,102 @@
+"""Tests for drydock.comms — the attention policy is a PURE function, so 'did it
+correctly stay silent?' is directly assertable (PRD §7/§24/§25)."""
+from drydock.comms import (
+    AttentionPolicy, AttentionConfig, Decision, Event, Presence, Severity,
+)
+
+
+def P(**kw):
+    return AttentionPolicy(cfg=AttentionConfig(**kw)) if kw else AttentionPolicy()
+
+
+def ev(t, **kw):
+    return Event(type=t, **kw)
+
+
+# ── routine noise stays quiet ────────────────────────────────────────────────
+def test_routine_activity_logs_or_ignores():
+    pol = P()
+    assert pol.decide(ev("task.progress", task_id="a")) <= Decision.LOG
+    assert pol.decide(ev("test.passed", task_id="a")) <= Decision.LOG
+    assert pol.decide(ev("task.started", severity=Severity.INFORMATIONAL)) <= Decision.DISPLAY
+
+
+def test_completion_surfaces_but_is_not_loud_when_away():
+    # task.completed is worth a message when the user is away, a display when present
+    pol = P()
+    assert pol.decide(ev("task.completed", task_id="a"), Presence.ACTIVE) == Decision.DISPLAY
+
+
+# ── INVARIANT: non-suppressible severities always reach the human ────────────
+def test_approval_required_is_non_suppressible():
+    pol = P()
+    for presence in (Presence.UNKNOWN, Presence.AWAY, Presence.ACTIVE, Presence.DO_NOT_DISTURB):
+        d = pol.decide(ev("decision.required", severity=Severity.APPROVAL_REQUIRED,
+                          requires_response=True, task_id="x"), presence)
+        assert d >= Decision.MESSAGE, (presence, d)
+
+
+def test_blocking_and_security_never_ignored_even_under_cooldown():
+    pol = P(cooldown_secs=9999)
+    for _ in range(5):  # would be cooled down if suppressible
+        d = pol.decide(ev("security.warning", severity=Severity.CRITICAL,
+                          summary="credentials found in repo", task_id="x"))
+        assert d >= Decision.MESSAGE
+    d = pol.decide(ev("error.blocking", severity=Severity.BLOCKING, task_id="y"))
+    assert d >= Decision.MESSAGE
+
+
+def test_hourly_breaker_never_gags_a_critical_event():
+    pol = P(max_notifies_per_hour=1)
+    pol.decide(ev("task.completed", severity=Severity.ADVISORY, requires_response=True))
+    # breaker is now tripped for loud channels, but a CRITICAL must still get through
+    d = pol.decide(ev("security.warning", severity=Severity.CRITICAL, summary="leak"))
+    assert d >= Decision.MESSAGE
+
+
+# ── presence routing ─────────────────────────────────────────────────────────
+def test_presence_routes_significant_events():
+    pol = P()
+    e = ev("decision.required", severity=Severity.APPROVAL_REQUIRED, requires_response=True, task_id="x")
+    assert pol.decide(e, Presence.VOICE) == Decision.SPEAK
+    assert P().decide(e, Presence.AWAY) == Decision.MESSAGE
+
+
+# ── anti-annoyance: cooldown + dedup + aggregation ──────────────────────────
+def test_single_test_failure_stays_quiet():
+    # a lone test.failed during the agent's own work is routine — it must NOT
+    # interrupt (the agent fixes it); only a stuck loop escalates.
+    pol = P()
+    assert pol.decide(ev("test.failed", severity=Severity.ADVISORY,
+                         summary="auth tests failing", task_id="a"), Presence.AWAY) <= Decision.LOG
+
+
+def test_repeated_notify_worthy_event_is_deduped_then_aggregated_once():
+    # agent.stuck IS notify-worthy (score 3). Repeated within cooldown → the first
+    # notifies, the rest are suppressed to LOG, and exactly one aggregated notice
+    # fires when repetition crosses the escalation threshold (PRD §25).
+    pol = P(cooldown_secs=9999, escalate_after=4)
+    e = ev("agent.stuck", severity=Severity.ADVISORY, summary="stuck on dep", task_id="a")
+    first = pol.decide(e, Presence.AWAY)
+    assert first >= Decision.MESSAGE               # first one gets through
+    seen = [pol.decide(e, Presence.AWAY) for _ in range(5)]
+    assert Decision.LOG in seen                    # dups suppressed inside cooldown
+    assert sum(1 for d in seen if d >= Decision.MESSAGE) == 1, "escalate exactly once"
+
+
+def test_non_suppressible_is_not_deduped_away():
+    pol = P(cooldown_secs=9999)
+    e = ev("permission.required", severity=Severity.APPROVAL_REQUIRED,
+           summary="delete credentials from git history?", requires_response=True, task_id="x")
+    decisions = [pol.decide(e) for _ in range(3)]
+    assert all(d >= Decision.MESSAGE for d in decisions), decisions
+
+
+# ── faithful wording for approvals ──────────────────────────────────────────
+def test_approval_summary_delivered_verbatim():
+    from drydock.comms.channels import format_for_human
+    e = ev("permission.required", severity=Severity.APPROVAL_REQUIRED,
+           summary="delete these credentials from git history?", requires_response=True,
+           task_id="repo")
+    out = format_for_human(e)
+    assert "delete these credentials from git history?" in out

drydock_cli-3.1.16/tests/test_declared_deps.py

@@ -0,0 +1,60 @@
+"""Regression guard for the v3.1.15 httpx bug: a module imported directly by the
+package MUST be declared in pyproject dependencies. Relying on transitive deps
+(httpx via openai, rich via textual) breaks a clean/partial `pip install` at
+runtime with ModuleNotFoundError; pypdf isn't transitive at all.
+
+This scans drydock/ with ast, drops stdlib + first-party, and asserts every
+remaining top-level import is a declared dependency. It would have failed on
+3.1.14 (httpx, pypdf, rich undeclared)."""
+import ast
+import sys
+import tomllib
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+PKG = ROOT / "drydock"
+
+# import-name -> distribution-name, only where they differ (none currently, but
+# future-proofs the check for e.g. PIL->pillow, yaml->pyyaml).
+IMPORT_TO_DIST = {"PIL": "pillow", "yaml": "pyyaml", "bs4": "beautifulsoup4"}
+
+
+def _declared_dists() -> set[str]:
+    data = tomllib.loads((ROOT / "pyproject.toml").read_text())
+    out = set()
+    for spec in data["project"]["dependencies"]:
+        # strip version/extras/markers → bare distribution name, normalized
+        name = spec.split(";")[0].split("[")[0]
+        for sep in ("==", ">=", "<=", "~=", ">", "<", "!=", " "):
+            name = name.split(sep)[0]
+        out.add(name.strip().lower().replace("_", "-"))
+    return out
+
+
+def _top_level_thirdparty_imports() -> set[str]:
+    stdlib = set(sys.stdlib_module_names)
+    mods: set[str] = set()
+    for py in PKG.rglob("*.py"):
+        tree = ast.parse(py.read_text(encoding="utf-8"), filename=str(py))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for a in node.names:
+                    mods.add(a.name.split(".")[0])
+            elif isinstance(node, ast.ImportFrom):
+                if node.level == 0 and node.module:  # skip relative imports
+                    mods.add(node.module.split(".")[0])
+    return {m for m in mods if m and m not in stdlib and m != "drydock"}
+
+
+def test_all_direct_imports_are_declared_dependencies():
+    declared = _declared_dists()
+    missing = []
+    for imp in sorted(_top_level_thirdparty_imports()):
+        dist = IMPORT_TO_DIST.get(imp, imp).lower().replace("_", "-")
+        if dist not in declared:
+            missing.append(f"{imp} (dist: {dist})")
+    assert not missing, (
+        "These packages are imported by drydock/ but NOT declared in "
+        f"pyproject dependencies (would break a clean pip install): {missing}. "
+        f"Declared: {sorted(declared)}"
+    )