dreadnode 2.0.17__tar.gz → 2.0.18__tar.gz

{dreadnode-2.0.17 → dreadnode-2.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dreadnode
-Version: 2.0.17
+Version: 2.0.18
 Summary: Dreadnode SDK
 Project-URL: Homepage, https://dreadnode.io
 Project-URL: Documentation, https://docs.dreadnode.io

{dreadnode-2.0.17 → dreadnode-2.0.18}/dreadnode/agents/__init__.py

@@ -28,6 +28,8 @@ __all__ = [
     "FunctionDefinition",
     "Hook",
     "JudgeResult",
+    "ProcessDecision",
+    "ProcessJudge",
     "Reaction",
     "Retry",
     "RetryWithFeedback",
@@ -44,6 +46,7 @@ __all__ = [
     "exceptions",
     "hooks",
     "mcp",
+    "process_judge_hook",
     "reactions",
     "skills",
     "stopping",
@@ -63,6 +66,9 @@ _LAZY_NAMES = frozenset(
         "Agent",
         "AgentJudge",
         "JudgeResult",
+        "ProcessDecision",
+        "ProcessJudge",
+        "process_judge_hook",
         "Trajectory",
         "Continue",
         "Fail",
@@ -94,6 +100,9 @@ def _lazy_init() -> None:
     # construction mirror for trajectory-scoring use cases.
     _Agent.Judge = _judge.AgentJudge
 
+    _process_judge = importlib.import_module("dreadnode.agents.process_judge")
+    _hooks = importlib.import_module("dreadnode.agents.hooks")
+
     g = globals()
     g["events"] = _events
     g["reactions"] = _reactions
@@ -101,6 +110,9 @@ def _lazy_init() -> None:
     g["Agent"] = _Agent
     g["AgentJudge"] = _judge.AgentJudge
     g["JudgeResult"] = _judge.JudgeResult
+    g["ProcessDecision"] = _process_judge.ProcessDecision
+    g["ProcessJudge"] = _process_judge.ProcessJudge
+    g["process_judge_hook"] = _hooks.process_judge_hook
     g["Trajectory"] = _Trajectory
     g["Continue"] = _reactions.Continue
     g["Fail"] = _reactions.Fail

{dreadnode-2.0.17 → dreadnode-2.0.18}/dreadnode/agents/hooks.py

@@ -12,10 +12,11 @@ from dataclasses import dataclass
 from dreadnode.agents.events import (
     AgentEvent,
     AgentStep,
+    GenerationStart,
     ToolEnd,
     ToolStart,
 )
-from dreadnode.agents.reactions import Reaction, Retry
+from dreadnode.agents.reactions import Fail, Finish, Reaction, Retry, RetryWithFeedback
 from dreadnode.core.hook import Hook, hook
 from dreadnode.generators.generator import Generator
 from dreadnode.generators.message import Message, make_compaction_message
@@ -23,6 +24,8 @@ from dreadnode.generators.message import Message, make_compaction_message
 if t.TYPE_CHECKING:
     from datetime import datetime
 
+    from dreadnode.agents.process_judge import ProcessJudge
+
 
 # =============================================================================
 # Tool Metrics
@@ -410,3 +413,167 @@ def _make_summarize_hook(
 
 # Pre-instantiated with defaults -- this is what the wrapper discovers
 summarize_when_long = _make_summarize_hook()
+
+
+# =============================================================================
+# Process Judge (guard policy)
+# =============================================================================
+
+TranscriptStrategy = t.Literal["intent_only", "intent_plus_outputs", "full"]
+OnDeny = t.Literal["retry", "finish"]
+OnJudgeError = t.Literal["deny", "allow", "fail"]
+
+
+def _strip_intent(messages: list[Message], strategy: TranscriptStrategy) -> list[Message]:
+    """Slice ``messages`` per ``strategy``.
+
+    - ``intent_only``: system + user-authored only. Smallest prompt and
+      narrowest attack surface (tool outputs never reach the judge).
+    - ``intent_plus_outputs``: above + tool-result messages. Catches
+      state drift but widens the surface — a malicious tool response
+      can carry prompt injection aimed at the judge.
+    - ``full``: messages unchanged.
+    """
+    if strategy == "full":
+        return list(messages)
+    if strategy == "intent_only":
+        return [m for m in messages if m.role in ("system", "user")]
+    if strategy == "intent_plus_outputs":
+        return [m for m in messages if m.role in ("system", "user", "tool")]
+    raise ValueError(f"unknown transcript_strategy: {strategy!r}")
+
+
+def _deny_reaction(reason: str, on_deny: OnDeny) -> Reaction:
+    if on_deny == "retry":
+        return RetryWithFeedback(feedback=reason)
+    return Finish(reason=f"policy denied: {reason}")
+
+
+def _judge_error_reaction(exc: Exception, on_judge_error: OnJudgeError) -> Reaction | None:
+    from loguru import logger
+
+    if on_judge_error == "deny":
+        return Finish(reason=f"process judge unreachable: {exc}")
+    if on_judge_error == "allow":
+        logger.warning("process judge errored, allowing tool call: {}", exc)
+        return None
+    return Fail(error=exc)
+
+
+def process_judge_hook(
+    judge: "ProcessJudge",
+    *,
+    transcript_strategy: TranscriptStrategy = "intent_only",
+    on_deny: OnDeny = "retry",
+    on_judge_error: OnJudgeError = "deny",
+    always_allow: t.Sequence[str] = (),
+    always_deny: t.Sequence[str] = (),
+    context_provider: t.Callable[[ToolStart], dict[str, t.Any]] | None = None,
+) -> Hook:
+    """Pre-tool-call gating hook backed by a :class:`ProcessJudge`.
+
+    Listens to ``GenerationStart`` to snapshot the message state going
+    into each generation, then judges every ``ToolStart`` against that
+    snapshot. ``always_allow`` / ``always_deny`` short-circuit the judge
+    call. ``always_deny`` wins ties.
+
+    Decisions map to reactions:
+
+    - allow → ``None`` (tool runs).
+    - deny + ``on_deny="retry"`` → :class:`RetryWithFeedback`.
+    - deny + ``on_deny="finish"`` → :class:`Finish` with ``"policy denied: …"``.
+    - judge raises + ``on_judge_error="deny"`` → :class:`Finish`.
+    - judge raises + ``on_judge_error="allow"`` → ``None`` plus warn-level log.
+    - judge raises + ``on_judge_error="fail"`` → :class:`Fail`.
+    """
+    import time
+
+    deny_set = set(always_deny)
+    allow_set = set(always_allow) - deny_set
+
+    _last_messages: list[Message] = []
+
+    @hook(AgentEvent)
+    async def process_judge_hook_inner(event: AgentEvent) -> Reaction | None:
+        nonlocal _last_messages
+        from dreadnode import log_metric
+
+        if isinstance(event, GenerationStart):
+            _last_messages = list(event.messages)
+            return None
+
+        if not isinstance(event, ToolStart):
+            return None
+
+        tool_name = event.tool_call.name
+        start = time.monotonic()
+
+        if tool_name in deny_set:
+            log_metric(
+                "process_judge.deny",
+                1,
+                attributes={
+                    "tool_name": tool_name,
+                    "short_circuit": True,
+                    "reason": "always_deny",
+                },
+            )
+            return _deny_reaction(f"tool {tool_name!r} is in always_deny list", on_deny)
+
+        if tool_name in allow_set:
+            log_metric(
+                "process_judge.allow",
+                1,
+                attributes={"tool_name": tool_name, "short_circuit": True},
+            )
+            return None
+
+        intent = _strip_intent(_last_messages, transcript_strategy)
+        context = context_provider(event) if context_provider else None
+
+        try:
+            decision = await judge.evaluate(
+                intent=intent,
+                proposed_call=event.tool_call,
+                context=context,
+            )
+        except Exception as exc:
+            latency_ms = int((time.monotonic() - start) * 1000)
+            log_metric(
+                "process_judge.error",
+                1,
+                attributes={
+                    "tool_name": tool_name,
+                    "error_type": type(exc).__name__,
+                    "error_message": str(exc),
+                    "latency_ms": latency_ms,
+                },
+            )
+            return _judge_error_reaction(exc, on_judge_error)
+
+        latency_ms = int((time.monotonic() - start) * 1000)
+        if decision.allow:
+            log_metric(
+                "process_judge.allow",
+                1,
+                attributes={
+                    "tool_name": tool_name,
+                    "short_circuit": False,
+                    "latency_ms": latency_ms,
+                },
+            )
+            return None
+
+        log_metric(
+            "process_judge.deny",
+            1,
+            attributes={
+                "tool_name": tool_name,
+                "short_circuit": False,
+                "reason": decision.reason,
+                "latency_ms": latency_ms,
+            },
+        )
+        return _deny_reaction(decision.reason, on_deny)
+
+    return process_judge_hook_inner

dreadnode-2.0.18/dreadnode/agents/process_judge.py

@@ -0,0 +1,207 @@
+"""ProcessJudge — LLM-backed gate over (intent, proposed tool call) pairs.
+
+The primitive layer of the guard policy. ``ProcessJudge`` knows
+nothing about ``Trajectory``, ``Hook``, or ``SessionPolicy`` — it takes
+pre-shaped inputs (a list of :class:`Message` plus a :class:`ToolCall`)
+and returns a :class:`ProcessDecision`. Hook code is responsible for the
+trajectory-to-intent transformation.
+
+Composition: reuses the lower-level :func:`dreadnode.scorers.judge.judge`
+function so XML response parsing and the regex fallback stay in one
+place. The default safety-floor rubric ships at
+``dreadnode/policies/rubrics/process/default.yaml`` and is layered with
+any user-supplied rubric under a ``## Project-specific scope`` header
+unless ``replace_default_rubric=True``.
+"""
+
+import typing as t
+from dataclasses import dataclass
+from pathlib import Path
+
+from dreadnode.generators.generator import GenerateParams, Generator, get_generator
+
+if t.TYPE_CHECKING:
+    from dreadnode.agents.tools import ToolCall
+    from dreadnode.generators.message import Message
+
+
+_DEFAULT_RUBRIC_PATH: Path = (
+    Path(__file__).parent.parent / "policies" / "rubrics" / "process" / "default.yaml"
+)
+
+_USER_RUBRIC_HEADER = "## Project-specific scope"
+
+
+@dataclass(slots=True)
+class ProcessDecision:
+    """Outcome of one :class:`ProcessJudge` invocation.
+
+    Two-valued by design — the agent will run an allowed call or won't run
+    a denied one. A "warn" mode is deliberately absent; the gating layer
+    cannot usefully half-allow a tool call.
+    """
+
+    allow: bool
+    reason: str
+
+
+class ProcessJudge:
+    """LLM-backed gate over (intent, proposed tool call) pairs.
+
+    Example::
+
+        from dreadnode.agents.process_judge import ProcessJudge
+
+        judge = ProcessJudge(
+            model="anthropic/claude-haiku-4-5",
+            rubric="In-scope domains: api.example.com",
+        )
+        decision = await judge.evaluate(
+            intent=session_messages,
+            proposed_call=tool_call,
+        )
+        if not decision.allow:
+            print("denied:", decision.reason)
+    """
+
+    def __init__(
+        self,
+        *,
+        model: str | Generator,
+        rubric: str | Path | None = None,
+        replace_default_rubric: bool = False,
+        model_params: dict[str, t.Any] | None = None,
+        system_prompt: str | None = None,
+    ) -> None:
+        if rubric is None and replace_default_rubric:
+            raise ValueError("replace_default_rubric=True requires a user-supplied rubric")
+
+        from dreadnode.scorers.judge import _load_rubric_from_yaml
+
+        default_text, default_system_prompt, _ = _load_rubric_from_yaml(
+            _DEFAULT_RUBRIC_PATH, system_prompt=None, name="process_default"
+        )
+
+        if rubric is None:
+            final_rubric = default_text
+        else:
+            user_text = self._resolve_user_rubric(rubric)
+            final_rubric = (
+                user_text
+                if replace_default_rubric
+                else f"{default_text}\n\n{_USER_RUBRIC_HEADER}\n{user_text}"
+            )
+
+        self._model = model
+        self._rubric = final_rubric
+        self._system_prompt = system_prompt or default_system_prompt
+        self._model_params = model_params
+
+    @property
+    def model(self) -> str | Generator:
+        return self._model
+
+    @property
+    def rubric(self) -> str:
+        return self._rubric
+
+    @property
+    def system_prompt(self) -> str | None:
+        return self._system_prompt
+
+    async def evaluate(
+        self,
+        *,
+        intent: "list[Message]",
+        proposed_call: "ToolCall",
+        context: dict[str, t.Any] | None = None,
+    ) -> ProcessDecision:
+        """Evaluate a proposed tool call against the rubric.
+
+        Args:
+            intent: Trajectory-stripped messages representing the user's
+                intent (typically system + user-authored, optionally tool
+                outputs depending on the hook's strategy).
+            proposed_call: The tool call about to execute. Wire name and
+                arguments are passed verbatim — argument redaction is a
+                separate concern.
+            context: Optional per-call context (task instruction, scope
+                metadata) merged into the rendered intent.
+
+        Returns:
+            A :class:`ProcessDecision` with ``allow`` and a short reason.
+        """
+        from dreadnode.scorers.judge import JudgeInput, judge
+
+        intent_text = self._render_intent(intent, context=context)
+        proposed_call_text = self._render_proposed_call(proposed_call)
+
+        generator = self._resolve_generator()
+        input_data = JudgeInput(
+            input=intent_text,
+            output=proposed_call_text,
+            rubric=self._rubric,
+        )
+
+        judgement = await judge(generator, input_data, system_prompt=self._system_prompt)
+        return ProcessDecision(allow=judgement.passing, reason=judgement.reason)
+
+    def _resolve_generator(self) -> Generator:
+        if isinstance(self._model, Generator):
+            return self._model
+        if not isinstance(self._model, str):
+            raise TypeError("model must be a string identifier or a Generator instance.")
+        params: GenerateParams | None
+        if self._model_params is None:
+            params = None
+        elif isinstance(self._model_params, GenerateParams):
+            params = self._model_params
+        else:
+            params = GenerateParams.model_validate(self._model_params)
+        return get_generator(self._model, params=params)
+
+    @staticmethod
+    def _resolve_user_rubric(rubric: str | Path) -> str:
+        """Resolve a user rubric to its body text.
+
+        Path or YAML-shaped string → load the YAML and read its ``rubric``
+        field. Anything else → treat as a plain string and return as-is.
+        """
+        from dreadnode.scorers.judge import _is_yaml_rubric, _load_rubric_from_yaml
+
+        if isinstance(rubric, Path) or _is_yaml_rubric(rubric):
+            text, _, _ = _load_rubric_from_yaml(rubric, system_prompt=None, name="user")
+            return text
+        return rubric
+
+    @staticmethod
+    def _render_intent(
+        intent: "list[Message]",
+        *,
+        context: dict[str, t.Any] | None = None,
+    ) -> str:
+        """Render intent messages as a transcript the judge can consume."""
+        lines: list[str] = []
+        if context:
+            lines.append("# Task context")
+            for key, value in context.items():
+                lines.append(f"- {key}: {value}")
+            lines.append("")
+        if intent:
+            lines.append("# Intent transcript")
+            for msg in intent:
+                role = getattr(msg, "role", "unknown")
+                content = getattr(msg, "content", "") or ""
+                lines.append(f"[{role}] {content}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _render_proposed_call(proposed_call: "ToolCall") -> str:
+        """Render the proposed tool call in a structured XML block."""
+        return (
+            f"<tool>{proposed_call.name}</tool>\n"
+            f"<arguments>{proposed_call.function.arguments}</arguments>"
+        )
+
+
+__all__ = ["ProcessDecision", "ProcessJudge"]

{dreadnode-2.0.17 → dreadnode-2.0.18}/dreadnode/app/cli/args.py

@@ -246,3 +246,19 @@ class TuiArgs(PlatformScopeArgs):
             help="Step budget for autonomous mode (defaults to 30)",
         ),
     ] = None
+    policy: t.Annotated[
+        str | None,
+        cyclopts.Parameter(
+            group=TUI_GROUP,
+            help="Session policy to launch with (e.g. 'guard'). Overrides --auto when set.",
+        ),
+    ] = None
+    policy_arg: t.Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            name="--policy-arg",
+            group=TUI_GROUP,
+            negative_iterable=(),
+            help="Policy parameter as key=value (repeatable). Forwarded to the policy spec.",
+        ),
+    ] = None

{dreadnode-2.0.17 → dreadnode-2.0.18}/dreadnode/app/cli/main.py

@@ -157,7 +157,20 @@ def create_app(tui_args: TuiArgs) -> "DreadnodeTextualApp":
         profile = None
 
     initial_policy: dict[str, t.Any] | None = None
-    if tui_args.auto:
+    if tui_args.policy:
+        from dreadnode.app.tui.app import _coerce_policy_arg
+
+        initial_policy = {"name": tui_args.policy}
+        for kv in tui_args.policy_arg or []:
+            if "=" not in kv:
+                raise ValueError(f"--policy-arg expects key=value, got {kv!r}")
+            key, _, value = kv.partition("=")
+            initial_policy[key.strip()] = _coerce_policy_arg(value.strip())
+        # `--max-steps` is a long-standing shortcut; honor it when the policy
+        # accepts a step budget but the user didn't explicitly pass it.
+        if tui_args.max_steps is not None and "max_steps" not in initial_policy:
+            initial_policy["max_steps"] = tui_args.max_steps
+    elif tui_args.auto:
         initial_policy = {"name": "headless"}
         if tui_args.max_steps is not None:
             initial_policy["max_steps"] = tui_args.max_steps