deepstrike 0.2.23__tar.gz → 0.2.24__tar.gz

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

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

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

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

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

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

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

@@ -64,7 +64,11 @@ from deepstrike.providers import (
     PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, ToolArgumentRepairedEvent,
     RetryConfig, CircuitBreaker, TokenUsage, ProviderToolSpec,
 )
-from deepstrike.tools import RegisteredTool, tool, streaming_tool, validate_tool_arguments, execute_tools, read_file
+from deepstrike.tools import (
+    RegisteredTool, tool, streaming_tool, validate_tool_arguments, execute_tools, read_file,
+    ToolError, safe_tool, ok, fail, format_tool_error,
+)
+from deepstrike.providers.stream import ToolAuditFailedEvent
 from deepstrike.memory import (
     WorkingMemory,
     DreamStore, DreamResult, SessionData, MemoryEntry, CurationResult, CurationStats,
@@ -139,6 +143,7 @@ __all__ = [
     "PermissionRequestEvent", "PermissionResolvedEvent", "PermissionResponse", "ToolArgumentRepairedEvent",
     "RetryConfig", "CircuitBreaker", "TokenUsage", "ProviderToolSpec",
     "RegisteredTool", "tool", "streaming_tool", "validate_tool_arguments", "execute_tools", "read_file",
+    "ToolError", "safe_tool", "ok", "fail", "format_tool_error", "ToolAuditFailedEvent",
     "WorkingMemory",
     "DreamStore", "DreamResult", "SessionData", "MemoryEntry", "CurationResult", "CurationStats",
     "PermissionManager", "PermissionMode", "Permission", "PermissionDecision",

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

@@ -126,6 +126,18 @@ class ToolDeniedEvent:
     reason: str = ""
 
 
+@dataclass
+class ToolAuditFailedEvent:
+    """A tool's ``ctx.audit(label, fn)`` best-effort side-effect threw. The tool itself completed
+    successfully (no ``is_error`` flip, no retry); this event lets the host log / monitor that an
+    audit-store / metrics-emit / non-essential persistence step failed."""
+    type: str = "tool_audit_failed"
+    call_id: str = ""
+    name: str = ""
+    label: str = ""
+    error: str = ""
+
+
 @dataclass
 class WorkflowNodesSubmittedEvent:
     """R3-1: a workflow node's agent called the ``submit_workflow_nodes`` tool. The runner surfaces
@@ -149,5 +161,6 @@ StreamEvent = Union[
     PermissionResolvedEvent,
     ToolArgumentRepairedEvent,
     ToolDeniedEvent,
+    ToolAuditFailedEvent,
     WorkflowNodesSubmittedEvent,
 ]

{deepstrike-0.2.23 → deepstrike-0.2.24}/deepstrike/runtime/execution_plane.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import asyncio
+import inspect
 import json
+import warnings
 from collections.abc import AsyncIterable, AsyncIterator
 from dataclasses import dataclass
 from pathlib import Path
@@ -13,12 +15,14 @@ from deepstrike.providers.stream import (
   PermissionResolvedEvent,
   PermissionResponse,
   StreamEvent,
+  ToolAuditFailedEvent,
   ToolDeltaEvent,
   ToolDeniedEvent,
   ToolResultEvent,
   ToolSuspendEvent,
   ToolArgumentRepairedEvent,
 )
+from deepstrike.tools.errors import format_tool_error
 from deepstrike.tools.registry import RegisteredTool, normalize_tool_chunk, tool_chunk_text, validate_tool_arguments
 
 if TYPE_CHECKING:
@@ -33,6 +37,39 @@ def _strip_frontmatter(content: str) -> str:
   return re.sub(r"^---\n.*?\n---\n?", "", content, count=1, flags=re.DOTALL)
 
 
+_WARNED_FAILURE_SHAPES: set[str] = set()
+
+
+def _maybe_warn_failure_shaped_chunk(tool_name: str, delta_text: str) -> None:
+  """One-shot heuristic: detect when a streaming tool yielded text that *looks* like a failure
+  envelope. The runtime cannot block the tool from doing it, but we warn (once per tool) so
+  the author migrates to raising — the canonical "streaming tool fails" path. Aligns with the
+  non-streaming ``tool()`` / ``safe_tool`` contract: failures raise, successes return data."""
+  if not delta_text or tool_name in _WARNED_FAILURE_SHAPES:
+    return
+  trimmed = delta_text.strip()
+  if len(trimmed) < 2 or trimmed[0] != "{":
+    return
+  try:
+    parsed = json.loads(trimmed)
+  except Exception:
+    return
+  if not isinstance(parsed, dict):
+    return
+  looks_like_failure = parsed.get("success") is False or parsed.get("isError") is True or parsed.get("is_error") is True
+  if not looks_like_failure:
+    return
+  _WARNED_FAILURE_SHAPES.add(tool_name)
+  warnings.warn(
+    f'streaming tool "{tool_name}" yielded a failure-shaped chunk '
+    "(success:false / isError:true). Streaming tools should fail by raising; the runtime will "
+    "catch and surface the error consistently. Returning a failure-shaped chunk is a foot-gun: "
+    "the kernel still sees is_error=False.",
+    RuntimeWarning,
+    stacklevel=2,
+  )
+
+
 @dataclass
 class RunContext:
   agent_id: str | None = None
@@ -45,6 +82,12 @@ class RunContext:
   # M3/G4: the working directory a sub-agent's tools should run in (the git worktree created for an
   # ``isolation: "worktree"`` node). Injected by ``WorktreeExecutionPlane``; a cwd-aware tool reads it.
   cwd: str | None = None
+  # Per-call best-effort side-effect helper (injected by the execution plane). Wrap audit-log
+  # writes, metrics emits, or any non-essential persistence in ``await ctx.audit(label, fn)``;
+  # if ``fn`` raises, the failure is surfaced as a ``ToolAuditFailedEvent`` and the tool still
+  # completes successfully — avoiding the foot-gun where a transient audit-store outage flips
+  # an already-committed write into ``is_error=True`` and triggers a duplicate retry.
+  audit: Callable[[str, Callable[[], Awaitable[None] | None]], Awaitable[None]] | None = None
 
 
 class ExecutionPlane:
@@ -174,6 +217,29 @@ class LocalExecutionPlane:
         error_kind="recoverable",
       )
       return
+    # Per-call ``audit`` helper: failures collected here are surfaced as
+    # ``ToolAuditFailedEvent`` rather than flipping the main tool result to ``is_error=True``.
+    audit_failures: list[tuple[str, str]] = []
+
+    async def _audit(label: str, fn: Callable[[], Awaitable[None] | None]) -> None:
+      try:
+        result = fn()
+        if inspect.isawaitable(result):
+          await result
+      except Exception as ae:
+        audit_failures.append((label, format_tool_error(ae)))
+
+    call_ctx = RunContext(
+      agent_id=ctx.agent_id,
+      skill_dir=ctx.skill_dir,
+      dream_store=ctx.dream_store,
+      knowledge_source=ctx.knowledge_source,
+      on_tool_suspend=ctx.on_tool_suspend,
+      on_permission_request=ctx.on_permission_request,
+      result_spool=ctx.result_spool,
+      cwd=ctx.cwd,
+      audit=_audit,
+    )
     try:
       kwargs = json.loads(call.arguments or "{}")
       original_args_str = json.dumps(kwargs)
@@ -195,8 +261,9 @@ class LocalExecutionPlane:
           original_arguments=original_args_str,
           repaired_arguments=json.dumps(kwargs),
         )
-      # M3/G4: pass the run context (incl. ``cwd``) so cwd-aware tools scope work to the worktree.
-      output = await registered(_ctx=ctx, **kwargs)
+      # M3/G4: pass the run context (incl. ``cwd``, ``audit``) so cwd-aware / audit-aware tools
+      # scope work to the worktree and route best-effort side-effects through the plane.
+      output = await registered(_ctx=call_ctx, **kwargs)
       if isinstance(output, AsyncIterable):
         combined = ""
         iterator = output.__aiter__()
@@ -234,22 +301,30 @@ class LocalExecutionPlane:
             continue
           delta = tool_chunk_text(raw)
           combined += delta
+          if delta:
+            _maybe_warn_failure_shaped_chunk(call.name, delta)
           yield ToolDeltaEvent(
             call_id=call.id, name=call.name, delta=delta,
             chunk=None if isinstance(raw, str) else chunk,
           )
+        for label, error in audit_failures:
+          yield ToolAuditFailedEvent(call_id=call.id, name=call.name, label=label, error=error)
         yield ToolResultEvent(call_id=call.id, name=call.name, content=combined, is_error=False)
         return
+      for label, error in audit_failures:
+        yield ToolAuditFailedEvent(call_id=call.id, name=call.name, label=label, error=error)
       yield ToolResultEvent(call_id=call.id, name=call.name, content=str(output), is_error=False)
     except Exception as exc:
       is_fatal = getattr(exc, "is_fatal", False)
       error_kind = getattr(exc, "error_kind", None)
       if error_kind is None:
         error_kind = "fatal" if is_fatal else "recoverable"
+      for label, error in audit_failures:
+        yield ToolAuditFailedEvent(call_id=call.id, name=call.name, label=label, error=error)
       yield ToolResultEvent(
         call_id=call.id,
         name=call.name,
-        content=str(exc),
+        content=format_tool_error(exc),
         is_error=True,
         is_fatal=is_fatal,
         error_kind=error_kind,

{deepstrike-0.2.23 → deepstrike-0.2.24}/deepstrike/runtime/mcp_proxy_plane.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any
 
 from deepstrike._kernel import ToolCall, ToolSchema
 from deepstrike.providers.stream import StreamEvent, ToolResultEvent
+from deepstrike.tools.errors import format_tool_error
 from deepstrike.tools.registry import RegisteredTool
 from deepstrike.runtime.execution_plane import ExecutionPlane, LocalExecutionPlane, RunContext
 from deepstrike.runtime.credential_vault import CredentialVault
@@ -126,7 +127,7 @@ class _McpConnection:
       )
       return (text or json.dumps(result)), result.get("isError", False)
     except Exception as exc:
-      return str(exc), True
+      return format_tool_error(exc), True
 
   async def stop(self) -> None:
     if self._reader_task:

{deepstrike-0.2.23 → deepstrike-0.2.24}/deepstrike/runtime/process_sandbox_plane.py

@@ -6,6 +6,7 @@ import os
 from pathlib import Path
 
 from deepstrike._kernel import ToolSchema
+from deepstrike.tools.errors import format_tool_error
 from deepstrike.tools.registry import RegisteredTool
 from deepstrike.runtime.execution_plane import LocalExecutionPlane
 
@@ -72,7 +73,7 @@ class ProcessSandboxPlane(LocalExecutionPlane):
         combined = combined[: self._max_output_bytes] + b"\n[output truncated]"
       return combined.decode("utf-8", errors="replace"), proc.returncode != 0
     except Exception as exc:
-      return str(exc), True
+      return format_tool_error(exc), True
 
   def _make_bash_tool(self) -> RegisteredTool:
     sandbox = self

{deepstrike-0.2.23 → deepstrike-0.2.24}/deepstrike/runtime/remote_vpc_plane.py

@@ -9,6 +9,7 @@ import aiohttp
 
 from deepstrike._kernel import ToolCall, ToolSchema
 from deepstrike.providers.stream import StreamEvent, ToolResultEvent
+from deepstrike.tools.errors import format_tool_error
 from deepstrike.tools.registry import RegisteredTool
 from deepstrike.runtime.execution_plane import LocalExecutionPlane, RunContext
 from deepstrike.runtime.credential_vault import CredentialVault
@@ -97,4 +98,4 @@ class RemoteVpcPlane:
           result: dict = await resp.json()
           return result.get("output", ""), bool(result.get("isError", False))
     except Exception as exc:
-      return str(exc), True
+      return format_tool_error(exc), True

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

@@ -37,6 +37,7 @@ from deepstrike.providers.stream import (
   WorkflowNodesSubmittedEvent,
 )
 from deepstrike.runtime.execution_plane import ExecutionPlane, LocalExecutionPlane, RunContext
+from deepstrike.tools.errors import format_tool_error
 from deepstrike.governance import governance_policy_to_kernel_event
 from deepstrike.runtime.kernel_event_log import kernel_observation_to_session_event, with_category
 from deepstrike.runtime.kernel_step import (
@@ -1449,7 +1450,7 @@ class RuntimeRunner:
                 id=evt.id, name=evt.name, arguments=json.dumps(evt.arguments),
               ))
         except Exception as exc:
-          err_msg = str(exc).lower()
+          err_msg = format_tool_error(exc).lower()
           if (
             ("413" in err_msg or "too long" in err_msg or "context length exceeded" in err_msg or "context_length_exceeded" in err_msg)
             and not has_attempted_reactive_compact
@@ -1462,7 +1463,7 @@ class RuntimeRunner:
               should_retry = True
           
           if not should_retry:
-            yield ErrorEvent(message=str(exc))
+            yield ErrorEvent(message=format_tool_error(exc))
             action = kernel_action(runtime, self._pending_observations, {"kind": "timeout"})
             break
 
@@ -1716,7 +1717,7 @@ class RuntimeRunner:
     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)
+      err_msg = format_tool_error(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)

deepstrike-0.2.24/deepstrike/tools/__init__.py

@@ -0,0 +1,9 @@
+from .registry import RegisteredTool, tool, streaming_tool, validate_tool_arguments
+from .execution import execute_tools
+from .builtin import read_file
+from .errors import ToolError, safe_tool, ok, fail, format_tool_error
+
+__all__ = [
+    "RegisteredTool", "tool", "streaming_tool", "validate_tool_arguments", "execute_tools", "read_file",
+    "ToolError", "safe_tool", "ok", "fail", "format_tool_error",
+]

deepstrike-0.2.24/deepstrike/tools/errors.py

@@ -0,0 +1,135 @@
+"""Tool error envelope + ``safe_tool`` decorator (Python parity for the Node ``tools/errors.ts``).
+
+Three pieces:
+
+- ``format_tool_error`` replaces the old ``str(exc)`` at SDK error sites: an ``Exception`` with
+  no extra fields gives ``str(exc)`` (the message); an exception carrying ``code`` / ``hint`` /
+  ``__cause__`` gives JSON; a non-exception value falls back to ``str(...)``.
+- ``ToolError`` is the canonical "the tool wants to fail with a code+hint" exception. Throwing it
+  from a ``safe_tool``-wrapped body produces ``{success:false, code, error, hint?}``.
+- ``safe_tool`` wraps a function so plain-data returns become ``{success:true, data}`` and any
+  raise becomes a fail envelope — opt-in equivalent of ``tool()`` for tools that want the
+  stable structured shape on the wire instead of free-form strings.
+
+The classic ``tool()`` factory is untouched; ``safe_tool`` is the migration path."""
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import AsyncIterable
+from typing import Any, Callable
+
+from .registry import RegisteredTool, _schema_for
+
+
+class ToolError(Exception):
+    """Carries machine-readable ``code`` + optional ``hint`` alongside the message. ``safe_tool``
+    converts a raised ``ToolError`` into ``{success:false, code, error, hint?}``. Code defaults
+    to ``"internal"`` so a bare ``raise ToolError("...")`` still produces a usable envelope."""
+
+    def __init__(self, message: str, *, code: str = "internal", hint: str | None = None,
+                 cause: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.hint = hint
+        if cause is not None:
+            self.__cause__ = cause
+
+
+def ok(data: Any = None) -> dict[str, Any]:
+    return {"success": True} if data is None else {"success": True, "data": data}
+
+
+def fail(code: str, error: str, hint: str | None = None) -> dict[str, Any]:
+    env: dict[str, Any] = {"success": False, "code": code, "error": error}
+    if hint is not None:
+        env["hint"] = hint
+    return env
+
+
+def _is_envelope(v: Any) -> bool:
+    return isinstance(v, dict) and isinstance(v.get("success"), bool)
+
+
+def format_tool_error(err: Any) -> str:
+    """Error-aware replacement for ``str(exc)`` / ``String(err)``.
+
+    - ``Exception`` with no extra fields → ``str(exc)`` (the message).
+    - ``Exception`` carrying ``code`` / ``hint`` / ``__cause__`` → JSON ``{message, name?, code?,
+      hint?, cause?}`` — agents can branch on ``code``.
+    - ``None`` / primitives / strings → ``str(...)`` unchanged.
+    - Other objects → ``json.dumps(...)`` if possible (replaces the old ``"<X object at 0x...>"``)."""
+    if err is None:
+        return "None"
+    if isinstance(err, str):
+        return err
+    if isinstance(err, BaseException):
+        code = getattr(err, "code", None)
+        hint = getattr(err, "hint", None)
+        cause = getattr(err, "__cause__", None)
+        if code is None and hint is None and cause is None:
+            return str(err) or type(err).__name__
+        payload: dict[str, Any] = {"message": str(err)}
+        name = type(err).__name__
+        if name not in ("Exception", "ToolError"):
+            payload["name"] = name
+        if code is not None:
+            payload["code"] = code
+        if hint is not None:
+            payload["hint"] = hint
+        if cause is not None:
+            payload["cause"] = str(cause) if isinstance(cause, BaseException) else cause
+        try:
+            return json.dumps(payload, default=str)
+        except Exception:
+            return str(err) or type(err).__name__
+    try:
+        return json.dumps(err, default=str)
+    except Exception:
+        return str(err)
+
+
+class _SafeRegisteredTool(RegisteredTool):
+    """``RegisteredTool`` subclass with the safe-envelope try/except baked into ``__call__``.
+
+    We can't reuse ``RegisteredTool``'s wrapper because that one stringifies the result; here we
+    serialize via ``json.dumps`` so the model receives a proper envelope, not ``str({...})``."""
+
+    async def __call__(self, _ctx: Any = None, **kwargs: Any) -> str:
+        if self._wants_ctx:
+            kwargs["ctx"] = _ctx
+        try:
+            result = self.fn(**kwargs)
+            if inspect.isawaitable(result):
+                result = await result
+            if isinstance(result, AsyncIterable):
+                # Streaming safe_tool: collect chunks, then envelope. Authors who want streaming
+                # output should use the classic ``streaming_tool`` + raise convention; ``safe_tool``
+                # is for the structured envelope path.
+                chunks: list[str] = []
+                async for chunk in result:
+                    chunks.append(chunk if isinstance(chunk, str) else str(chunk))
+                result = "".join(chunks)
+            if _is_envelope(result):
+                return json.dumps(result)
+            return json.dumps(ok(result))
+        except ToolError as e:
+            return json.dumps(fail(e.code, str(e) or type(e).__name__, e.hint))
+        except Exception as e:
+            code = getattr(e, "code", None)
+            hint = getattr(e, "hint", None)
+            code_str = code if isinstance(code, str) else "internal"
+            hint_str = hint if isinstance(hint, str) else None
+            return json.dumps(fail(code_str, str(e) or type(e).__name__, hint_str))
+
+
+def safe_tool(fn: Callable) -> RegisteredTool:
+    """``tool()`` equivalent that wraps the body in a try/except and returns a stable
+    ``{success, code, error, hint?}`` JSON envelope to the model. Drop-in: ``@safe_tool``
+    instead of ``@tool``.
+
+    The body may return plain data (auto-wrapped as ``ok(data)``), an envelope produced by
+    ``ok()`` / ``fail()`` (passed through), or raise — ``ToolError`` becomes a fail envelope
+    with the ``code`` and ``hint``; any other ``Exception`` becomes ``{success:false, code:
+    err.code if str else "internal", error: str(err)}``."""
+    return _SafeRegisteredTool(fn, _schema_for(fn))

{deepstrike-0.2.23 → deepstrike-0.2.24}/deepstrike/tools/execution.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 import json
 from deepstrike._kernel import ToolCall, ToolResult
 from collections.abc import AsyncIterable
+from .errors import format_tool_error
 from .registry import RegisteredTool, tool_chunk_text, validate_tool_arguments
 
 
@@ -29,5 +30,5 @@ async def execute_tools(
                 output = "".join(chunks)
             results.append(ToolResult(call_id=call.id, output=str(output)))
         except Exception as exc:
-            results.append(ToolResult(call_id=call.id, output=str(exc), is_error=True))
+            results.append(ToolResult(call_id=call.id, output=format_tool_error(exc), is_error=True))
     return results

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

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

deepstrike-0.2.23/deepstrike/tools/__init__.py

@@ -1,5 +0,0 @@
-from .registry import RegisteredTool, tool, streaming_tool, validate_tool_arguments
-from .execution import execute_tools
-from .builtin import read_file
-
-__all__ = ["RegisteredTool", "tool", "streaming_tool", "validate_tool_arguments", "execute_tools", "read_file"]