Skip to content
BranchesTags

Repository files navigation

DHMS / AgentFuse

License: Apache-2.0 Python Install Evidence Docs

Current local package identity: dhms-agentfuse 3.6.0.

Historical evidence milestone: v3.5.2. Evidence schema: agentfuse-evidence-schema-v0.1.

Experimental in-process policy and authorization-boundary control for AI agent tools.

The integrating runtime constructs and validates its own approval and action contracts before mapping trusted context into a ToolCallRequest. AgentFuse evaluates that request against configured static or custom policy and returns canonical allow or block evidence. Its invocation APIs can enforce that decision before a Python tool handler; its decision-only APIs leave dispatch and physical outcome ownership with the integrating runtime.

The existing Evidence Schema, denial fixtures, LangChain proof chain, and langgraph_bigtool.create_agent() wiring remain supporting evidence.

AI agents increasingly call tools that can mutate SQL, files, APIs, code, or business systems. DHMS / AgentFuse focuses on the execution boundary before a tool's protected payload runs. The integrating application validates and supplies trusted capability, risk, approval, and business-policy context. AgentFuse evaluates the mapped ToolCallRequest against configured policy and fails closed on policy exceptions or malformed policy results.

A high-risk action may be allowed when trusted policy explicitly permits it and the integrating runtime has validated all required approval conditions. A seemingly harmless action may be blocked by configured AgentFuse policy even when the integrating runtime considers its approval contract valid.

Chinese overview: README.zh-CN.md

Quickstart

pip install -e .
python examples/runtime_guard/runtime_guard_mvp_demo.py
python examples/runtime_guard/langgraph_runtime_guard_demo.py

Expected final verdicts:

AGENTFUSE_RUNTIME_GUARD_MVP_DEMO_PASS
AGENTFUSE_LANGGRAPH_RUNTIME_GUARD_DEMO_PASS

If your system python is older than Python 3.10, use a Python 3.11 runtime:

/usr/local/bin/python3.11 -m pip install -e .
/usr/local/bin/python3.11 examples/runtime_guard/runtime_guard_mvp_demo.py
/usr/local/bin/python3.11 examples/runtime_guard/langgraph_runtime_guard_demo.py

AgentFuse Runtime Guard MVP

The Runtime Guard solves one narrow problem: evaluate policy before dispatching an agent tool handler, block disallowed execution, and generate structured execution or non-execution evidence from the same control path.

Synchronous Handler

from dhms_agentfuse import RuntimeGuard, ToolCallRequest

guard = RuntimeGuard(
    allow_tools={"search", "read_file"},
    deny_tools={"delete_file", "execute_sql", "send_external_message"},
    default_action="block",
)

result = guard.invoke(
    tool_call=ToolCallRequest(
        tool_call_id="call-001",
        tool_name="delete_file",
        arguments={"path": "synthetic-example.txt"},
    ),
    handler=delete_file_handler,
)

assert result.outcome == "not_executed"
assert result.handler_invoked is False

An explicit denylist match has highest precedence. When allow_tools is configured, a tool absent from that set is blocked. A custom policy may further allow or block calls that pass static configuration; policy exceptions and invalid decisions fail closed.

from dhms_agentfuse import RuntimePolicyDecision

def policy(tool_call):
    if tool_call.safe_metadata.get("requires_approval"):
        return RuntimePolicyDecision.block("policy_denied")
    return RuntimePolicyDecision.allow()

guard = RuntimeGuard(default_action="block", policy=policy)

Decision-Only API

Use evaluate() when another runtime owns approval, dispatch, and physical outcome recording:

decision = guard.evaluate(tool_call)

assert decision.action in {"allow", "block"}
assert decision.evidence.schema_version == "agentfuse-evidence-schema-v0.1"

For asynchronous custom policies, use await guard.aevaluate(tool_call). Neither method accepts a handler, dispatches a tool, or performs the protected side effect. invoke() and ainvoke() use the same decision path and may dispatch only after that public decision allows the call.

See docs/dhms_agentfuse_public_decision_api_v3_6_0.md for the complete contract.

Responsibility Boundary

The integrating application owns

  • ActionProposal creation
  • ActionApproval creation
  • proposal digest validation
  • approval identity, expiry, and generation validation
  • project, session, task, and action identity validation
  • trusted capability and risk classification
  • business and organizational safety policy
  • physical handler dispatch
  • physical outcome recording and recovery

Risk classification must come from trusted application configuration or another deterministic application-owned source. It must not be inferred by AgentFuse from prompt text, model arguments, provider metadata, or command output. The integrating runtime must validate its approval and action contracts before mapping trusted context into a ToolCallRequest.

The bridge or adapter owns

  • protocol mapping
  • trusted metadata mapping
  • request and response identity validation
  • source, schema, policy revision, and protocol checks

Trusted values may be placed in ToolCallRequest.safe_metadata for a custom policy to inspect. AgentFuse 3.6.0 does not define or universally validate an external runtime's approval schema.

AgentFuse owns

  • deterministic ToolCallRequest policy evaluation
  • canonical allow or block decision evidence
  • fail-closed handling of policy errors and malformed policy results

AgentFuse does not own

  • intrinsic danger classification
  • user-intent interpretation
  • business correctness
  • malware detection
  • physical execution
  • universal interception of unwrapped paths

When an external Action Runtime is used, it persists the decision, prevents dispatch without a valid durable allow decision, invokes the physical handler, and records the physical outcome.

Decision vocabulary is intentionally bounded:

AGENTFUSE_CORE_INPUT=ToolCallRequest
AGENTFUSE_CORE_DECISIONS=allow|block
AGENTFUSE_CORE_APPROVAL_CONTRACT=false
AGENTFUSE_CORE_HOLD_DECISION=false
KERNIQ_MAPPED_DECISIONS=allow|deny|error
AGENTFUSE_HOLD_SUPPORTED=false

hold is part of KerniQ's generic ActionDecision contract, but the canonical AgentFuse 3.6.0 bridge does not emit it.

DHMS_IS_A_DANGER_CLASSIFIER=false
DHMS_IS_A_POLICY_AND_AUTHORIZATION_BOUNDARY=true
RISK_CLASSIFICATION_OWNER=INTEGRATING_APPLICATION
PHYSICAL_DISPATCH_OWNER=INTEGRATING_APPLICATION

Real Consumer Integration: KerniQ

KerniQ v0.6.0 is an external consumer of the public AgentFuse 3.6.0 decision-only API. Its merged PR #6 pins AgentFuse source commit ec4b5842339dccfba0db62df7541920759203bc9 and calls:

decision = guard.evaluate(tool_call)

KerniQ Action Runtime constructs and validates ActionProposal and ActionApproval, including proposal digest, approval identity, expiry, generation, and action, project, session, and task identity. The KerniQ bridge validates request identity before mapping the validated request and trusted context into AgentFuse ToolCallRequest.

AgentFuse then evaluates the mapped request against a trusted allow/block policy and emits canonical evidence. The KerniQ adapter validates the returned decision identity, source commit, schema, policy revision, and protocol, then maps AgentFuse allow to KerniQ allow, AgentFuse block to KerniQ deny, and bridge or validation failure to KerniQ error.

AgentFuse does not own KerniQ's physical handler. KerniQ owns durable ACTION_DECIDED persistence, dispatch, ACTION_STARTED, physical execution, settlement, and restart recovery.

The merged integration verified these bounded properties:

  • a durable allow decision precedes dispatch;
  • deny results in zero handler invocations;
  • malformed or stale identities fail closed in the KerniQ bridge or adapter;
  • settlement persistence uncertainty becomes Interrupted;
  • interrupted actions are not automatically replayed;
  • tampered installed AgentFuse source fails closed; and
  • mutable installation metadata cannot bless tampered source.

The current KerniQ integration covers one bounded proof action. Project Command, Patch, Git, file-write, shell, MCP, browser, Office, provider, and other production action paths are not yet claimed to be protected by AgentFuse.

See the public decision API contract and KerniQ merge commit 3d333a30e4507e796aa97ddc0142606ad2e42587 for the stable integration references.

Asynchronous Handler

result = await guard.ainvoke(
    tool_call=tool_call,
    handler=async_handler,
)

Use ainvoke for async handlers or async custom policies. The guard does not run async handlers through an implicit event loop.

Sequential Batch

from dhms_agentfuse import GuardedInvocation

results = guard.invoke_batch(
    invocations=[
        GuardedInvocation(tool_call=blocked_call, handler=blocked_handler),
        GuardedInvocation(tool_call=allowed_call, handler=allowed_handler),
    ]
)

Each input receives one result in input order. A blocked call, policy failure, or handler exception does not suppress later calls in the sequential batch.

LangGraph ToolNode

from langgraph.graph import MessagesState, StateGraph
from dhms_agentfuse import LangGraphRuntimeGuardAdapter

adapter = LangGraphRuntimeGuardAdapter(guard)
builder = StateGraph(MessagesState)
builder.add_node("tools", adapter.create_tool_node([read_file, delete_file]))
builder.set_entry_point("tools")
builder.set_finish_point("tools")
graph = builder.compile()

The adapter uses the installed LangGraph ToolNode dispatch path. Blocked calls receive a terminal ToolMessage bound to the original tool-call ID; allowed handlers use normal ToolNode execution; handler exceptions remain terminal execution failures rather than policy denials. Evidence receipts are available through adapter.receipts and adapter.receipt_for(tool_call_id).

Representative safe output:

delete_file:
decision=block
outcome=not_executed
handler_invoked=false

read_project_summary:
decision=allow
outcome=executed
handler_invoked=true

The Runtime Guard MVP guarantees only that handlers passed through the guard are evaluated before dispatch, blocked handlers are not called by that guarded path, and evidence is generated by that path. Successful return values remain available on result.return_value but are excluded from to_safe_dict() and the default representation.

AgentFuse Runtime Guard MVP is an experimental in-process pre-dispatch control layer. It is not a process sandbox, network firewall, or universal production-security boundary. Application code can still call handlers directly; other processes, subprocesses, monkey-patching, network traffic, and unwrapped LangGraph paths are not automatically intercepted. It provides no enterprise-security, compliance, certification, or universal side-effect prevention guarantee.

Supporting External-Facing Proof

  • Current branch: agent-harness-v1.
  • Supporting proof chain: v3.4.2 frozen multi-tool selective interception result review.
  • Latest external-facing demo: v3.5.2 real langgraph_bigtool.create_agent() API wiring.
  • Demo path: examples/external_integrations/langgraph_bigtool/.
  • safe_read_only_summary_tool returns RELEASE_CANDIDATE.
  • dangerous_sql_mutation_tool fails closed with blocked category sql_mutation.
  • model_api_request_tool fails closed with blocked category model_api.
  • protected_payload_body_execution_count = 0.
  • runtime_behaviors_added = 0.
  • execution_authorized_count = 0.

v3.5.2 remains the latest historical external-project wiring demo. The Runtime Guard MVP above is now the primary current-use path; v3.4.2 and v3.5.2 remain supporting proof-chain checkpoints.

AgentFuse Evidence Schema v0.1

AgentFuse Evidence Schema v0.1 represents blocked agent tool calls as completed policy decisions, not failed tool executions. It captures policy resolution, non-execution evidence, layered boundary decisions, and safe trace metadata for guarded tool-call proposals.

The schema keeps approval and execution as separate lifecycle facts. A denied tool call can carry status=not_executed, execution=not_started, a reason code, safe policy metadata, and an evidence reference without exposing raw arguments, raw paths, environment variables, request bodies, secrets, or other sensitive payloads in default traces.

This is feedback-informed schema/demo work, not a production runtime security claim. It preserves the existing boundary: no live graph invocation is required, no provider calls are made, no protected payload executes, and no raw sensitive inputs are included in default traces.

Five-Minute Per-Call Denial Trial

After pip install -e ., run:

python examples/trial/per_call_denial_lifecycle_demo.py

The deterministic two-call batch denies one mutation-style call before its handler starts, then executes one inert read-only handler exactly once. Both calls receive terminal lifecycle records, and the denied call does not abort the allowed call. Expected verdict:

AGENTFUSE_PER_CALL_DENIAL_TRIAL_DEMO_PASS

This is a local schema/demo example. It does not invoke a provider, model, network, database, SQL system, graph, credential source, or external service, and it does not claim production runtime protection.

Regression Fixtures for Denied Tool Calls

The provider-neutral, copyable fixtures cover terminal denial records, preserved tool-call identity, and allowed-call continuation after a denial. They are in examples/trial/denial_lifecycle_regression_fixtures/fixtures.json with a concise fixture README. The existing trial demo remains the runnable reference.

Table of Contents

Overview

DHMS began as memory/context/tool-state perturbation testing. The agent-harness-v1 branch is the public DHMS AgentFuse evidence line for the DHMS Execution Fuse Protocol.

What DHMS Does

DHMS / AgentFuse provides an experimental in-process Runtime Guard for side-effect-capable AI agent tools. It evaluates exact calls against allowlist, denylist, default, and optional custom policies before guarded handler dispatch and emits safe receipts. The integrating application, not AgentFuse, owns trusted risk classification, approval requirements, and physical execution. Existing schema and proof artifacts remain available for regression and portability work.

What DHMS Does Not Claim

DHMS / AgentFuse is not claiming universal production runtime protection. The Runtime Guard controls only handlers routed through its API or its explicit LangGraph adapter. Direct calls and unwrapped execution paths remain possible.

The historical v3.5.2 demo:

  • does not compile, invoke, or stream the graph
  • does not call providers, networks, databases, SQL systems, credentials, or user data
  • does not call providers or real model APIs
  • does not perform network requests
  • does not access databases
  • does not execute SQL
  • does not read credentials, environment variables, or user data
  • does not authorize protected payload execution
  • does not claim to protect live production LangGraph agents
  • does not claim LangChain or LangGraph lacks safety mechanisms
  • does not claim DHMS is a finished enterprise security product

Latest Demo

The two current Runtime Guard demos perform real guarded handler dispatch and a real installed-LangGraph ToolNode graph invocation with deterministic, in-memory handlers. They make no provider or model call and perform no real file, SQL, network, or messaging operation.

The historical v3.5.2 demo remains available to demonstrate langgraph_bigtool.create_agent() API wiring. It builds a guarded registry but does not compile, invoke, or stream that historical graph.

Evidence Chain

The strongest frozen proof-chain foundation remains v3.4.2: a local deterministic real LangChain multi-tool selective interception boundary where one real LangChain agent has three adapter-created guarded tools. DHMS evaluates each tool call independently before protected payload execution, safe read-only returns RELEASE_CANDIDATE, sql_mutation and model_api fail closed, and all protected payload bodies remain unexecuted with sentinel/count evidence.

Evidence field Frozen value
Dependency requirements.txt with langchain>=1.0,<2.0
Runtime and LangChain /usr/local/bin/python3.11, observed LangChain 1.3.11
Reusable guarded adapter dhms_agentfuse/langchain_guarded_tool_adapter.py with reusable adapter APIs
Real LangChain agent loop real_create_agent_imported=true, real_langchain_agent_object_created=true, real agent loop invoked, fake/local driver used, ToolMessage and tool boundary observed
Scenario matrix single_agent_boundary_count=1, registered_adapter_created_tool_count=3, independent_tool_call_count=3
Gate results safe_read_only_release_candidate_count=1, sql_mutation_fail_closed_count=1, model_api_fail_closed_count=1
Sentinel proof all side_effect_sentinel_before=0, side_effect_sentinel_after=0, side_effect_sentinel_delta=0; protected_payload_body_invocation_count=0
Execution/runtime boundary execution_authorized_count=0, runtime_behaviors_added=0
Frozen marker DHMS_REAL_LANGCHAIN_MULTI_TOOL_SELECTIVE_INTERCEPTION_VALIDATION_PASS

Reproduce The Proof

/usr/local/bin/python3.11 validation/run_dhms_langchain_multi_tool_selective_interception_validation_v0.py

Expected output summary: DHMS_REAL_LANGCHAIN_MULTI_TOOL_SELECTIVE_INTERCEPTION_VALIDATION_PASS, single_agent_boundary_count=1, registered_adapter_created_tool_count=3, same_agent_tool_registry=true, independent_tool_call_count=3, safe_read_only_release_candidate_count=1, sql_mutation_fail_closed_count=1, model_api_fail_closed_count=1, all_protected_tool_body_executed_false=true, all_side_effect_sentinel_after_zero=true, execution_authorized_count=0, runtime_behaviors_added=0, sentinel_failure_count=0, protected_payload_body_execution_count=0.

pyproject.toml makes the local dhms_agentfuse package editable-installable. requirements.txt remains the dependency model for LangChain validation dependencies. This is not a PyPI release or package release.

Feedback Wanted

Feedback is especially useful on whether the guarded tool registry boundary is easy to understand, whether the v3.5.2 non-claims are clear enough, and which side-effect-capable tool risks should be prioritized next.

Legacy v2.7 pre-execution proof command:

python3 validation/run_dhms_pre_execution_fuse_loop_proof_v0.py

Screenshot Evidence

docs/development/screenshots/v2_7_3_pre_execution_interception_proof/v2_7_3_pre_execution_interception_proof_terminal.png

The screenshot captures the v2.7.3 proof command output:

python3 validation/run_dhms_pre_execution_fuse_loop_proof_v0.py

This is not a screenshot of:

python3 cli.py gate-proposal examples/proposals/drop_table.json

The v3.0 gate-proposal CLI line is separate from the v2.7 screenshot proof.

View v2.7.3 proof screenshot

v2.7.3 pre-execution interception proof

v2.7 Evidence Chain

v2.8 Evidence Chain

v2.9 Evidence Chain

v3.0 Evidence Chain

v3.1 Evidence Chain

v3.2 Evidence Chain

Milestone Evidence Boundary
v3.2.0 Real LangChain agent loop pre-tool boundary harness Real LangChain agent-loop pre-tool boundary; sentinel proves the executable payload did not run
v3.2.1 Three-run boundary validation All three independent runs kept sentinel=0; the payload body did not execute
v3.2.2 Result review + README sync Assertion records frozen; public boundary synced

Links: v3.2.0 harness doc, v3.2.0 validator, v3.2.1 validator, v3.2.1 assertion records, v3.2.2 result review.

v3.3 Evidence Chain

Milestone Evidence Boundary
v3.3.0 Reusable real LangChain guarded tool adapter boundary expansion Adapter wraps multiple executable local payload bodies; protected payloads remain unexecuted
v3.3.1 3-scenario x 3-run guarded adapter validation Nine real LangChain adapter-loop executions keep sentinel=0 and payload bodies unexecuted
v3.3.2 Result review + README sync Assertion records frozen; README and public boundary synced

Links: v3.3.0 adapter module, v3.3.0 validator, v3.3.1 validator, v3.3.1 assertion records, v3.3.2 result review, v3.3.2 README sync.

v3.4 Evidence Chain

Milestone Evidence Boundary
v3.4.0 Multi-tool selective interception boundary + static spec One real LangChain agent boundary with three adapter-created tools
v3.4.1 Single-agent three-tool validation Same agent/tool registry; 1 release-candidate, 2 fail-closed; payload bodies unexecuted
v3.4.2 Result review + README sync Assertion records frozen; public boundary synced

Links: v3.4.0 boundary doc, v3.4.0 static spec, v3.4.1 validator, v3.4.1 assertion records, v3.4.2 result review.

v3.5 Packaging and External API Wiring

Milestone Evidence Boundary
v3.5.0 Editable local package install pip install -e . works locally; requirements.txt remains the dependency model
v3.5.1 DHMS guard demo based on the langgraph-bigtool tool registry pattern Mirrors the registry shape without importing or running langgraph_bigtool; safe call returns RELEASE_CANDIDATE, dangerous calls fail closed
v3.5.2 Real langgraph_bigtool.create_agent API wiring demo Builds a guarded registry before create_agent(), uses deterministic retrieval, and does not compile/invoke/stream the agent graph

Links: editable package metadata, v3.5.2 real API wiring doc, v3.5.2 example README, v3.5.2 demo.

Public Boundary

DHMS v3.5.2 shows real langgraph_bigtool.create_agent() API wiring with a guarded tool registry. The frozen v3.4.2 proof remains the strongest multi-tool selective interception evidence. Neither is a production safety claim.

Current public boundaries:

  • No production readiness or real-world agent/database protection is claimed.
  • No arbitrary production LangChain agent protection, arbitrary real-world agent protection, tool execution, model-provider call, execution authorization, or runtime behavior is claimed or added.
  • The historical v3.5.2 demo includes no SQLDatabaseToolkit, SQL Agent, database, model-provider, E2B, MCP, external-runtime, or production-runtime integration.
  • The separate KerniQ v0.6.0 consumer integration is bounded to one development proof action and does not extend protection claims to Project Command, Patch, Git, file-write, shell, MCP, browser, Office, provider, or other production action paths.
  • No v2.7 CLI gate-proposal support is claimed; python3 cli.py gate-proposal examples/proposals/drop_table.json is explicitly not part of the v2.7 proof.
  • The current proof remains bounded to a local deterministic real LangChain agent loop, fake/local model driver, reusable guarded adapter boundary, one agent with three adapter-created tools, RELEASE_CANDIDATE for safe read-only proposals, FAIL_CLOSED for sql_mutation and model_api, execution authorization false, sentinel/count proof, and zero runtime behavior added.
  • The next direction is packaging, integration example, public posting, and external feedback, not another internal proof expansion.

For the detailed non-claims and freeze boundary, see:

Historical Evidence Lines

Quickstart For Older Evidence

python3 cli.py demo-sql-fuse
python3 cli.py demo-file-fuse
python3 cli.py demo-http-fuse
python3 validation/run_dhms_mock_agent_interception_benchmark_v0.py
python3 cli.py bench-mock-agent-interception
python3 validation/run_dhms_controlled_mock_agent_runtime_interception_proof.py
python3 cli.py proof-mock-agent-interception
python3 validation/run_dhms_local_command_proposal_benchmark_v0.py
python3 validation/run_dhms_controlled_mock_agent_local_command_interception_proof.py
python3 validation/run_dhms_runtime_adapter_proposal_benchmark_v0.py
python3 validation/run_dhms_controlled_mock_agent_runtime_adapter_boundary_proof.py

Fresh-clone reproduction is documented in DHMS Fresh Clone Reproduction Check v1.0.1.

Documentation Index

Historical Release Materials

Architecture Note

main keeps the Product Diagnosis v1.3 public checkpoint for perturbation-based LLM memory/context stability testing. The agent-harness-v1 branch layers Agent Harness preview work on top of DHMS without changing protected DHMS theory, metrics, binding, or engine semantics.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

Copyright 2026 Huaxinsheng Zhong.

Trademark Notice

DHMS, DHMS Engine, DHMS AgentFuse, and DHMS Agent Harness are project names and marks of Huaxinsheng Zhong.

Use of these names is permitted for accurate reference to this project, but does not imply endorsement, sponsorship, or affiliation unless explicitly authorized.

The Apache-2.0 license applies to the source code and documentation in this repository. It does not grant trademark rights.

About

DHMS: Automatic fail-closed execution fuse for side-effect-capable AI agent tools - built from memory/context/tool-state perturbation testing toward runtime execution control.

Topics

agent-evaluationagent-safetyai-safetydry-runevidence-basedllm-agentsmemory-safetyrag-securitysafety-testingsemantic-safety

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages