cayu.testing.verify_tool_effect
Part of cayu.testing.base. Read the Python API overview and install the required extra.
from cayu.testing import verify_tool_effectInvoke one registered tool against a bounded, isolated temporary workspace.
NONE receives a scoped consistency verdict. IDEMPOTENT and
EXTERNAL require allow_effectful_execution=True and are observed
once without a replay-safety verdict. The tool runs directly: runtime
policy, hooks, events, and the model loop are intentionally outside this
deployment-readiness seam. One cooperative asyncio deadline covers seeding,
both workspace snapshots, tool execution, and cleanup. Expiration raises
TimeoutError without returning a verdict. A blocking tool or filesystem
operation can delay that failure; a hard stop requires a process boundary.
ProcessIsolatedTool is rejected because invoking it directly would bypass
its runtime-owned process and recovery boundary.
Arguments are validated and copied as portable durable JSON before the tool
can be invoked.
async verify_tool_effect(app: CayuApp, *, agent_name: str, tool_name: str, arguments: Mapping[str, Any], workspace_files: Mapping[str, bytes] | None=None, unobserved_systems: Iterable[str]=(), session_id: str='tool-effect-verification', idempotency_key: str | None=None, metadata: Mapping[str, Any] | None=None, allow_effectful_execution: bool=False, timeout_seconds: float=_DEFAULT_TIMEOUT_SECONDS, max_entries: int=_DEFAULT_MAX_ENTRIES, max_files: int=_DEFAULT_MAX_FILES, max_file_bytes: int=_DEFAULT_MAX_FILE_BYTES, max_total_bytes: int=_DEFAULT_MAX_TOTAL_BYTES) -> ToolEffectVerification