deepstrike 0.2.22__tar.gz → 0.2.23__tar.gz

{deepstrike-0.2.22 → deepstrike-0.2.23}/Cargo.lock

@@ -194,7 +194,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-core"
-version = "0.2.22"
+version = "0.2.23"
 dependencies = [
  "compact_str",
  "pretty_assertions",
@@ -206,7 +206,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-node"
-version = "0.2.22"
+version = "0.2.23"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -218,7 +218,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-py"
-version = "0.2.22"
+version = "0.2.23"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -229,7 +229,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-sdk"
-version = "0.2.22"
+version = "0.2.23"
 dependencies = [
  "async-stream",
  "async-trait",
@@ -263,7 +263,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-wasm"
-version = "0.2.22"
+version = "0.2.23"
 dependencies = [
  "compact_str",
  "deepstrike-core",

{deepstrike-0.2.22 → deepstrike-0.2.23}/Cargo.toml

@@ -3,13 +3,13 @@ resolver = "2"
 members = ["crates/deepstrike-core", "crates/deepstrike-py"]
 
 [workspace.package]
-version = "0.2.22"
+version = "0.2.23"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/kongusen/deepstrike"
 
 [workspace.dependencies]
-deepstrike-core = { path = "crates/deepstrike-core", version = "0.2.22" }
+deepstrike-core = { path = "crates/deepstrike-core", version = "0.2.23" }
 notify = "6"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

{deepstrike-0.2.22 → deepstrike-0.2.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepstrike
-Version: 0.2.22
+Version: 0.2.23
 Requires-Dist: httpx>=0.27
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: anyio>=4.0

{deepstrike-0.2.22 → deepstrike-0.2.23}/deepstrike/__init__.py

@@ -75,6 +75,9 @@ from deepstrike.harness import (
     QualityGate,
     SinglePassHarness, HarnessLoop, EvalLoopHarness,
     HarnessRequest, HarnessOutcome,
+    # I3.1: surface harness types so hosts can construct verdicts and stream-event handlers
+    # without importing from deepstrike.harness.harness directly.
+    HarnessEvent, CriterionResult,
 )
 from deepstrike.skills import SkillRegistry
 from deepstrike.knowledge import KnowledgeSource
@@ -141,6 +144,7 @@ __all__ = [
     "PermissionManager", "PermissionMode", "Permission", "PermissionDecision",
     "QualityGate",
     "SinglePassHarness", "HarnessLoop", "EvalLoopHarness", "HarnessRequest", "HarnessOutcome",
+    "HarnessEvent", "CriterionResult",
     "SkillRegistry",
     "KnowledgeSource",
     "RuntimeSignal", "SignalSource", "ScheduledPrompt", "SignalGateway",

{deepstrike-0.2.22 → deepstrike-0.2.23}/deepstrike/governance.py

@@ -28,6 +28,38 @@ class GovernancePolicy:
     vetoes: list[str] = field(default_factory=list)
     rate_limits: list[GovernanceRateLimit] = field(default_factory=list)
     constraints: list[dict[str, Any]] = field(default_factory=list)
+    # I5: when True (default), the runner pre-filters denied tools out of the schema. Mirrors Node.
+    surface_denied_in_system: bool = True
+
+
+def governance_filter_schema(tools: list, policy: "GovernancePolicy | None") -> tuple[list, list[str]]:
+    """I5: bucket tools into (allowed, denied) per the policy. Pure. Mirrors Node ``governanceFilterSchema``."""
+    if policy is None:
+        return tools, []
+    vetoes = set(policy.vetoes or [])
+    allowed: list = []
+    denied: list[str] = []
+    def matches(pat: str, name: str) -> bool:
+        return pat == name or (pat.endswith("*") and name.startswith(pat[:-1]))
+    for t in tools:
+        name = t.name if hasattr(t, "name") else (t.get("name") if isinstance(t, dict) else None)
+        if name is None:
+            allowed.append(t)
+            continue
+        if name in vetoes:
+            denied.append(name)
+            continue
+        action = policy.default_action or "allow"
+        for r in (policy.rules or []):
+            pat = r.pattern if hasattr(r, "pattern") else r.get("pattern")
+            act = r.action if hasattr(r, "action") else r.get("action")
+            if pat is not None and matches(pat, name):
+                action = act
+        if action == "deny":
+            denied.append(name)
+        else:
+            allowed.append(t)
+    return allowed, denied
 
 
 def governance_policy_to_kernel_event(policy: GovernancePolicy) -> dict[str, Any]:

{deepstrike-0.2.22 → deepstrike-0.2.23}/deepstrike/harness/harness.py

@@ -16,6 +16,10 @@ class Criterion:
     text: str
     required: bool = True
     weight: float = 1.0
+    # I3.3 (A4): optional stable id from the host's contract layer (threaded to verdict_fn).
+    id: "str | None" = None
+    # I3.3 (A4): host hint — host has a deterministic check for this criterion.
+    machine_checkable: "bool | None" = None
 
 
 @dataclass
@@ -160,6 +164,9 @@ class SinglePassHarness:
 
 
 class EvalLoopHarness:
+    """I3.4 (A1): deprecated — prefer ``HarnessLoop`` with ``verdict_fn`` for host-defined
+    judgment. ``EvalLoopHarness.stream()`` does NOT honor ``gate`` (only ``.run()`` does);
+    ``HarnessLoop`` runs the eval loop uniformly across stream and run."""
     def __init__(self, runner: "RuntimeRunner", gate: "QualityGate", max_attempts: int = 3):
         self._runner = runner
         self._gate = gate
@@ -186,11 +193,16 @@ class HarnessLoop:
         *,
         max_attempts: int = 3,
         skill_dir: str | None = None,
+        # I3.2 (A2/A3): host-supplied judgment. Receives kwargs (goal, criteria, attempt, result);
+        # returns Verdict to short-circuit the LLM eval, or None/Awaitable[None] to defer. Mirrors
+        # the Node SDK ``verdictFn``.
+        verdict_fn=None,
     ):
         self._runner = runner
         self._eval_provider = eval_provider
         self._max_attempts = max_attempts
         self._skill_dir = pathlib.Path(skill_dir) if skill_dir else None
+        self._verdict_fn = verdict_fn
 
     async def run(self, request: HarnessRequest) -> HarnessOutcome:
         # R3-1: collect nodes the agent submits while running under the harness (dynamic fan-out in
@@ -251,30 +263,41 @@ class HarnessLoop:
 
             yield SupervisingEvent()
 
-            # #6 (0.5.0): the eval/verdict compute is the kernel's stateless free functions (was the
-            # EvalPipeline state machine). Build the eval prompt, call the eval LLM, parse the verdict.
-            eval_msgs = build_eval_messages(request.goal, criteria, last_result, attempt, True)
-            eval_text = ""
-            eval_system = "\n\n".join(m.content for m in eval_msgs if m.role == "system")
-            eval_turns = [m for m in eval_msgs if m.role != "system"]
-            eval_context = RenderedContext(system_text=eval_system, turns=eval_turns)
-            async for evt in self._eval_provider.stream(eval_context, [], extensions=None):
-                if isinstance(evt, TextDelta):
-                    eval_text += evt.delta
-
-            parsed = parse_verdict(eval_text)
-            verdict = Verdict(
-                passed=parsed.passed,
-                overall_score=parsed.overall_score,
-                feedback=parsed.feedback,
-                details=[
-                    CriterionResult(criterion=d.criterion, passed=d.passed, score=d.score, feedback=d.feedback)
-                    for d in (parsed.details or [])
-                ],
-            )
+            # I3.2 (A2/A3): host-supplied verdict_fn short-circuits the LLM eval. Returning None
+            # (or awaitable None) defers to the built-in eval below — enables hybrid judgment.
+            verdict = None
+            skill_candidate = None
+            if self._verdict_fn is not None:
+                result = self._verdict_fn(goal=request.goal, criteria=criteria, attempt=attempt, result=last_result)
+                if hasattr(result, "__await__"):
+                    result = await result
+                verdict = result
+            if verdict is None:
+                # #6 (0.5.0): the eval/verdict compute is the kernel's stateless free functions (was the
+                # EvalPipeline state machine). Build the eval prompt, call the eval LLM, parse the verdict.
+                eval_msgs = build_eval_messages(request.goal, criteria, last_result, attempt, True)
+                eval_text = ""
+                eval_system = "\n\n".join(m.content for m in eval_msgs if m.role == "system")
+                eval_turns = [m for m in eval_msgs if m.role != "system"]
+                eval_context = RenderedContext(system_text=eval_system, turns=eval_turns)
+                async for evt in self._eval_provider.stream(eval_context, [], extensions=None):
+                    if isinstance(evt, TextDelta):
+                        eval_text += evt.delta
+
+                parsed = parse_verdict(eval_text)
+                verdict = Verdict(
+                    passed=parsed.passed,
+                    overall_score=parsed.overall_score,
+                    feedback=parsed.feedback,
+                    details=[
+                        CriterionResult(criterion=d.criterion, passed=d.passed, score=d.score, feedback=d.feedback)
+                        for d in (parsed.details or [])
+                    ],
+                )
+                skill_candidate = parsed.skill_candidate
 
             if verdict.passed:
-                sc = parsed.skill_candidate
+                sc = skill_candidate
                 if sc and self._skill_dir:
                     lines = ["---", f"name: {sc.name}", f"description: {sc.description}"]
                     if sc.when_to_use:

{deepstrike-0.2.22 → deepstrike-0.2.23}/deepstrike/providers/anthropic.py

@@ -222,6 +222,8 @@ class AnthropicProvider:
         system = self._build_system(context, strategy)
         tool_defs = self._build_tools(tools, anchor_cache=not isinstance(system, list), strategy=strategy)
         _assert_cache_budget(system, len(tools))
+        # I1: capture which slots will carry cache_control for pro-rata attribution at usage time.
+        slot_bp = _count_cache_control_slots(system, tool_defs, msgs)
 
         native_blocks: dict[int, dict] = {}
         tool_blocks: dict[int, dict] = {}
@@ -254,12 +256,14 @@ class AnthropicProvider:
                         # input_tokens is the FULL prompt size (uncached + cache
                         # read + cache write) for accurate context accounting.
                         full_input = uncached_input + cache_read + cache_creation
+                        by_slot = _estimate_cache_read_by_slot(cache_read, slot_bp)
                         yield UsageEvent(
                             total_tokens=full_input + output_tokens,
                             input_tokens=full_input,
                             output_tokens=output_tokens,
                             cache_read_input_tokens=cache_read,
                             cache_creation_input_tokens=cache_creation,
+                            cache_read_input_tokens_by_slot=by_slot,
                         )
                 elif event.type == "content_block_start":
                     idx = event.index
@@ -341,6 +345,37 @@ def _resolve_cache_breakpoint_strategy(extensions: "dict | None") -> str:
     return "default"
 
 
+def _count_cache_control_slots(system, tool_defs, msgs) -> dict:
+    """I1: which slots of the outgoing request carry a ``cache_control`` breakpoint. Mirrors Node."""
+    sys_bp = isinstance(system, list) and any((isinstance(b, dict) and b.get("cache_control") is not None) for b in system)
+    tool_bp = bool(tool_defs) and any((isinstance(t, dict) and t.get("cache_control") is not None) for t in tool_defs)
+    msg_bp = False
+    for m in msgs or []:
+        content = m.get("content") if isinstance(m, dict) else None
+        if isinstance(content, list):
+            if any((isinstance(b, dict) and b.get("cache_control") is not None) for b in content):
+                msg_bp = True
+                break
+    return {"system": sys_bp, "tools": tool_bp, "messages": msg_bp}
+
+
+def _estimate_cache_read_by_slot(cache_read: int, slot_bp: dict) -> "dict | None":
+    """I1: split ``cache_read_input_tokens`` evenly across contributing slots. Remainder lands on the
+    first contributing slot to keep the sum exact. Returns None when no cache read or no slot
+    contributed — consumers see the field absent rather than all zeros. Mirrors Node."""
+    if cache_read <= 0:
+        return None
+    contributors = [s for s in ("system", "tools", "messages") if slot_bp.get(s)]
+    if not contributors:
+        return None
+    share = cache_read // len(contributors)
+    remainder = cache_read - share * len(contributors)
+    out: dict = {}
+    for i, slot in enumerate(contributors):
+        out[slot] = share + (remainder if i == 0 else 0)
+    return out
+
+
 def _apply_message_cache_control(msgs: list[dict], frozen_prefix_len: "int | None" = None, strategy: str = "default") -> None:
     """Place the (<=2) message-history cache breakpoints. The final message always
     gets one (writes the current full prefix). The second is placed by one of two

{deepstrike-0.2.22 → deepstrike-0.2.23}/deepstrike/providers/stream.py

@@ -63,6 +63,9 @@ class UsageEvent:
     # Cost breakdown (subset of input_tokens): reads bill ~0.1x, writes ~1.25x.
     cache_read_input_tokens: int = 0
     cache_creation_input_tokens: int = 0
+    # I1: pro-rata per-slot attribution of cache_read_input_tokens (Anthropic only). None when the
+    # provider doesn't honor cache_control. Shape: {"system": int?, "tools": int?, "messages": int?}.
+    cache_read_input_tokens_by_slot: "dict | None" = None
 
 
 @dataclass

{deepstrike-0.2.22 → deepstrike-0.2.23}/deepstrike/runtime/runner.py

@@ -133,6 +133,8 @@ class TurnMetrics:
   cache_read_tokens: int
   cache_creation_tokens: int
   active_skill: str | None = None
+  # I1: pro-rata per-slot attribution of cache_read_tokens (Anthropic only). Mirrors Node.
+  cache_read_tokens_by_slot: "dict | None" = None
 
 
 @dataclass
@@ -154,6 +156,10 @@ class RuntimeOptions:
   max_total_tokens: int | None = None
   timeout_ms: int | None = None
   agent_id: str | None = None
+  # I4: run-start memory pre-fetch hook. Callable receiving kwarg `goal=`; returns a list of query
+  # strings (or None). Each query becomes a dreamStore search; hits page into the knowledge
+  # partition before turn 1. Requires dream_store + agent_id. Errs-open. Mirrors Node ``preQueryMemory``.
+  pre_query_memory: "Callable[..., Any] | None" = None
   system_prompt: str | None = None
   initial_memory: list[str] | None = None
   skill_dir: str | Path | None = None
@@ -1334,6 +1340,25 @@ class RuntimeRunner:
         "message": {"role": "user", "content": list(attachments)},
       })
 
+    # I4: pre-fetch memory into the knowledge partition before the first LLM turn (mirrors Node).
+    if not resume_mid_run and self._opts.pre_query_memory and self._opts.dream_store and self._opts.agent_id:
+      try:
+        result = self._opts.pre_query_memory(goal=goal)
+        if hasattr(result, "__await__"):
+          result = await result
+        queries = result or []
+        entries = []
+        for q in queries:
+          if not isinstance(q, str) or not q.strip():
+            continue
+          hits = await self._opts.dream_store.search(self._opts.agent_id, q, 5)
+          for hit in hits:
+            entries.append({"content": f"[memory score={hit.score:.3f}] {hit.text}", "source": "memory"})
+        if entries:
+          kernel_apply(runtime, self._pending_observations, {"kind": "page_in", "entries": entries})
+      except Exception:
+        pass  # errs-open
+
     action = (
       kernel_action(runtime, self._pending_observations, {"kind": "resume"})
       if resume_mid_run
@@ -1343,7 +1368,9 @@ class RuntimeRunner:
     # P0-C: the skill loaded and in effect going into the current turn → per-turn ``active_skill`` metric.
     active_skill: str | None = None
 
-    while not runtime.is_terminal():
+    # I0b: kernel-throw safety net — see Node runner for full rationale.
+    try:
+     while not runtime.is_terminal():
       if action.kind == "execute_tool":
         await self._apply_kernel_page_in(runtime, session_id)
       next_compressed_archive_start = await self._append_observations(
@@ -1360,6 +1387,9 @@ class RuntimeRunner:
           sig_action = kernel_maybe_action(runtime, self._pending_observations, _signal_to_kernel_event(sig))
           if sig_action:
             action = sig_action
+          # I0a: Critical signal carries user_abort intent; see Node runner for full rationale.
+          if getattr(sig, "urgency", None) == "critical":
+            self._interrupted = True
       if runtime.is_terminal():
         break
 
@@ -1372,14 +1402,29 @@ class RuntimeRunner:
         final_tool_calls: list[ToolCall] = []
         final_text = ""
         context = action.context or RenderedContext()
+        # I5: governance schema-level pre-filter — mirrors Node. Tools that the policy denies are
+        # dropped from the schema before the provider sees them; the model never tries them.
+        turn_tools = action.tools or []
+        if self._opts.governance_policy and getattr(self._opts.governance_policy, "surface_denied_in_system", True):
+          from deepstrike.governance import governance_filter_schema as _gov_filter
+          allowed, denied = _gov_filter(turn_tools, self._opts.governance_policy)
+          if denied:
+            turn_tools = allowed
+            note = f"[governance] the following tools are denied for this run and will fail if called: {', '.join(denied)}."
+            existing = getattr(context, "system_knowledge", "") or ""
+            try:
+              context = type(context)(**{**context.__dict__, "system_knowledge": f"{existing}\n\n{note}".strip()})
+            except Exception:
+              pass  # don't break the run if the context can't be cloned
         turn_tokens = 0
         turn_input_tokens = 0
         turn_cache_read_tokens = 0
         turn_cache_creation_tokens = 0
+        turn_cache_read_by_slot = None
         should_retry = False
         try:
           async for evt in self._opts.provider.stream(
-            context, action.tools or [], extensions=ext if ext else None, state=provider_state,
+            context, turn_tools, extensions=ext if ext else None, state=provider_state,
           ):
             # #2-B-ii: a preempting interrupt() stops consuming the live stream immediately; breaking
             # the `async for` closes the provider's async generator → its httpx context exits → the
@@ -1393,6 +1438,8 @@ class RuntimeRunner:
               turn_input_tokens = getattr(evt, "input_tokens", 0) or 0
               turn_cache_read_tokens = getattr(evt, "cache_read_input_tokens", 0) or 0
               turn_cache_creation_tokens = getattr(evt, "cache_creation_input_tokens", 0) or 0
+              # I1: per-slot attribution forwarded to TurnMetrics; None on non-Anthropic providers.
+              turn_cache_read_by_slot = getattr(evt, "cache_read_input_tokens_by_slot", None)
               continue
             yield evt
             if isinstance(evt, TextDelta):
@@ -1466,6 +1513,7 @@ class RuntimeRunner:
         # INTO this turn; a ``skill`` call here only takes effect next turn — emit first, then advance.
         if self._opts.on_turn_metrics is not None:
           try:
+            _tm_kwargs_by_slot = {"cache_read_tokens_by_slot": turn_cache_read_by_slot} if turn_cache_read_by_slot else {}
             self._opts.on_turn_metrics(TurnMetrics(
               turn=runtime.turn(),
               tools_exposed=len(action.tools or []),
@@ -1474,6 +1522,7 @@ class RuntimeRunner:
               cache_read_tokens=turn_cache_read_tokens,
               cache_creation_tokens=turn_cache_creation_tokens,
               active_skill=active_skill,
+              **_tm_kwargs_by_slot,
             ))
           except Exception:
             pass  # metrics must never break the run
@@ -1664,9 +1713,29 @@ class RuntimeRunner:
 
       elif action.kind == "done":
         break
+    except Exception as err:
+      # I0b: kernel rejection (or any other thrown error inside the loop) is observable here — emit
+      # run_terminal so downstream code sees a clean end rather than mid-loop EOF.
+      err_msg = str(err)
+      is_invalid_arg = "invalidarg" in err_msg.lower() or "invalid argument" in err_msg.lower()
+      reason = "invalid_arg" if is_invalid_arg else "error"
+      yield ErrorEvent(message=err_msg)
+      try:
+        await self._opts.session_log.append(session_id, build_run_terminal_event(
+          reason=reason,
+          turns_used=runtime.turn() or 0,
+          total_tokens=0,
+        ))
+      except Exception:
+        pass  # session log failure must not mask the original error
+      yield DoneEvent(iterations=runtime.turn() or 0, total_tokens=0, status=reason)
+      self._active_kernel = None
+      self._current_session_id = None
+      return
 
     result = action.result if action.kind == "done" else None
-    status = result.termination if result else "error"
+    # I0a: preserve preempt intent when loop exits without clean kernel-done (see Node runner for full rationale).
+    status = result.termination if result else ("user_abort" if self._interrupted else "error")
     turns_used = max(1, result.turns_used) if result else (runtime.turn() or 0)
     total_tokens = result.total_tokens_used if result else 0
 

{deepstrike-0.2.22 → deepstrike-0.2.23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "deepstrike"
-version = "0.2.22"
+version = "0.2.23"
 requires-python = ">=3.10"
 readme = "README.md"
 dependencies = [