DHMS / AgentFuse

AgentFuse is a fail-closed pre-dispatch execution boundary for side-effect-capable AI agent tools.

An integrating runtime validates its own action, approval, identity, risk, and business-policy contracts, maps trusted context into a ToolCallRequest, and asks AgentFuse for a canonical allow or block decision. AgentFuse can return that decision without dispatch or enforce it before a handler supplied through the guarded invocation path.

AgentFuse is not a process sandbox, malware detector, intrinsic danger classifier, or universal interceptor for unwrapped execution paths.

Chinese overview: README.zh-CN.md

Experimental Public Beta

The supported public paths are RuntimeGuard, the explicit LangGraph ToolNode integration, and immutable integration metadata. A protected call reaches its handler only when the trusted policy boundary returns allow.

Install

PyPI publication is not currently available. Install the tagged public-beta package from GitHub:

python -m pip install \
  "dhms-agentfuse @ git+https://github.com/MkaliezZ/dhms-engine.git@v3.7.3"

The v3.7.3 GitHub Release also provides a wheel and source distribution.

Five-Minute Beta Trial

No LLM provider, API key, or runtime external service is required:

git clone --branch v3.7.3 --depth 1 \
  https://github.com/MkaliezZ/dhms-engine.git agentfuse-beta
cd agentfuse-beta
python -m pip install -e . "langgraph==1.2.11"
python examples/integration_trial/five_minute_v3_7_1/run_trial.py

The bounded trial runs one allowed handler exactly once and one blocked handler zero times. See the full five-minute trial guide.

AgentFuse Public Beta

Maintain an agent runtime or an agent with side-effect-capable tools? Open a Beta Integration Request with your repository, runtime/framework, and one protected tool. The form is designed to take under one minute and starts a bounded integration discussion; it does not promise indefinite engineering support.

Current Status

PACKAGE=dhms-agentfuse 3.7.3
STATUS=experimental-public-beta
PUBLIC_API=RuntimeGuardDecision|evaluate|aevaluate|invoke|ainvoke
INTEGRATION_API=IntegrationProfile|list_integrations|get_integration
EVIDENCE_SCHEMA=agentfuse-evidence-schema-v0.1
HISTORICAL_EVIDENCE_MILESTONE=v3.5.2
CURRENT_BRANCH=agent-harness-v1

Current externally relevant evidence:

• KerniQ v0.6.1 Project Command — a bounded native Desktop Project Command path is gated by explicit application approval, a durable AgentFuse decision, durable start evidence, and KerniQ-owned native execution. The reviewed real Tauri proof is frozen.
• KerniQ v0.7 Coding Pack Export — a separate bounded export profile uses AgentFuse 3.6.0 before durable export start; the native atomic-export path passed a controlled real macOS proof and the v0.7 line is frozen.
• Hermes #53021 external threat-model proof — a standalone proof models a deny-by-default session terminal allowlist and verifies pre-dispatch blocking, retry identity, deterministic re-evaluation, and safe receipts. It does not modify Hermes and is not a production Hermes integration.
• Historical v3.5.2 external-project wiring demo — real langgraph_bigtool.create_agent() API wiring remains a historical evidence checkpoint; it is not the current package version.

The v3.7.0 Multi-Runtime Integration Package exposes immutable metadata profiles for the reviewed RuntimeGuard, reference, LangGraph, and external DSH mappings. The registry packages tested capabilities and evidence boundaries; it does not execute tools, discover runtimes, or claim that different hosts share one universal lifecycle. The underlying 14-case v3.6.2 matrix remains frozen at 52 PASS, 4 justified N/A, and 0 FAIL.

The v3.7.3 Integration Release Seal and its machine-readable record freeze the exact review and post-merge compatibility evidence behind this public beta without changing runtime behavior.

Maintainer Checks

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

Expected final verdicts:

AGENTFUSE_RUNTIME_GUARD_MVP_DEMO_PASS
AGENTFUSE_LANGGRAPH_RUNTIME_GUARD_DEMO_PASS
AGENTFUSE_CROSS_ADAPTER_CONFORMANCE_V3_6_2_PASS

Inspect the reviewed integration mappings without runtime discovery:

from dhms_agentfuse.integrations import get_integration, list_integrations

profiles = list_integrations()
langgraph = get_integration("langgraph-tool-node")
assert langgraph.tested_version == "1.2.11"

The returned profiles are metadata-only and immutable. Capability names mean the tested path can observe or represent that fact; they do not transfer host lifecycle ownership to AgentFuse.

Run the bounded LangGraph consumer integration trial with no LLM, API key, or runtime network service:

pip install -e . "langgraph==1.2.11"
python examples/integration_trial/five_minute_v3_7_1/run_trial.py
python examples/integration_trial/five_minute_v3_7_1/run_trial.py --json-only

At the tested langgraph==1.2.11 version, the selected allow handler runs once and the selected blocked handler runs zero times through the wrapped ToolNode. The full v3.7.1 trial guide describes the public consumer imports, clean-wheel proof, and boundaries. The trial is designed as an approximately-five-minute workflow; it does not claim external human timing or adoption validation.

AgentFuse v3.7.2 adds a bounded GitHub Actions compatibility matrix for the exact Python/LangGraph cells recorded in validation/compatibility_v3_7_2/compatibility_matrix.json. The matrix builds one wheel and reuses it across repository-external public-API probes. Tested cells are evidence only for those exact combinations; the declared langgraph>=1.2,<2.0 dependency range is not proof that every eligible version is compatible. See the v3.7.2 compatibility guide.

Run the latest external threat-model proof:

python examples/external_integrations/hermes_53021/session_allowlist_proof.py
python -m pytest tests/test_hermes_53021_external_proof.py -q

Expected verdict:

AGENTFUSE_HERMES_53021_EXTERNAL_PROOF_PASS

If your system python is older than Python 3.10, use a Python 3.11 runtime. The install instructions above intentionally use the tagged GitHub source; this README does not claim a PyPI release.

Runtime Guard

The Runtime Guard evaluates a tool call before guarded dispatch, blocks calls rejected by configured policy, and produces structured decision or execution evidence from the same control path.

Decision-only API

Use evaluate() when another runtime owns approval, persistence, 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).

evaluate() and aevaluate() accept no handler and perform no protected side effect. invoke() and ainvoke() reuse the same public decision path and may dispatch only after that path allows the call.

Decision API baseline: AgentFuse Public Decision API 3.6.0. Consumer lifecycle boundary: AgentFuse Consumer Integration Contract 3.6.1.

Responsibility Boundary

The integrating application owns

• ActionProposal and ActionApproval creation and validation
• proposal digest, approval identity, expiry, and generation validation
• project, session, task, and action identity validation
• trusted capability and risk classification
• business and organizational safety policy
• durable lifecycle rules around the decision
• physical dispatch, 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 bridge or adapter owns

• protocol and 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.7.3 does not define or universally validate another runtime's approval schema.

AgentFuse owns

• deterministic ToolCallRequest policy evaluation
• canonical allow or block decision evidence
• fail-closed handling of policy exceptions and malformed policy results
• pre-dispatch enforcement only for handlers routed through guarded invocation APIs

AgentFuse does not own

• intrinsic danger classification
• user-intent interpretation
• business correctness
• malware detection
• physical execution owned by another runtime
• universal interception of direct or unwrapped execution paths

AGENTFUSE_CORE_INPUT=ToolCallRequest
AGENTFUSE_CORE_DECISIONS=allow|block
AGENTFUSE_CORE_APPROVAL_CONTRACT=false
AGENTFUSE_CORE_HOLD_DECISION=false
DHMS_IS_A_DANGER_CLASSIFIER=false
DHMS_IS_A_POLICY_AND_AUTHORIZATION_BOUNDARY=true
RISK_CLASSIFICATION_OWNER=INTEGRATING_APPLICATION
PHYSICAL_DISPATCH_OWNER=INTEGRATING_APPLICATION

KerniQ maps AgentFuse allow|block into its own application vocabulary. hold exists in KerniQ's generic action contract but is not emitted by the canonical AgentFuse 3.6.0 bridge.

Real Consumer Integration: KerniQ

KerniQ is a real external consumer of the public AgentFuse 3.6.0 decision-only API. Its pinned canonical AgentFuse source for the frozen consumer proofs is commit ec4b5842339dccfba0db62df7541920759203bc9.

KerniQ owns proposal and approval contracts, lifecycle persistence, dispatch, execution, settlement, and recovery. AgentFuse evaluates the mapped ToolCallRequest; the KerniQ bridge and adapter validate source, protocol, policy, schema, request, and response identity before the application treats the decision as dispatch authority.

Frozen boundary 1: Project Command v0.6.1

The bounded native Desktop Project Command path uses the kerniq-project-command-v1 profile. The reviewed chain proves, within that path:

• explicit application approval before AgentFuse evaluation;
• a durable AgentFuse decision before COMMAND_STARTED;
• zero native dispatch for deny/block, stale authority, cancellation before start, and decision/start persistence failures;
• Rust-side trusted catalog re-resolution and direct no-shell execution;
• truthful Interrupted state when settlement persistence is uncertain; and
• restart no-replay with controlled-lifecycle at-most-once behavior in the reviewed proof scope.

References: freeze activation merge · real Tauri proof PR #14

Frozen boundary 2: Coding Pack Export v0.7

The separate kerniq-coding-pack-export-v1 profile governs one bounded Coding Pack export lifecycle. The reviewed chain proves, within that path:

• exact proposal and confirmation identity before policy evaluation;
• a digest-only AgentFuse request with no raw source content or absolute local path;
• durable PACK_DECIDED allow|deny|error evidence before export start;
• zero destination writes when the durable allow/start boundary is not satisfied;
• native source revalidation, same-filesystem staging, and no-overwrite atomic promotion on the proven macOS path; and
• truthful uncertainty when terminal persistence or post-promotion sync cannot be proven.

The controlled real native proof passed and the v0.7 Coding Pack line is frozen.

References: v0.7 freeze merge · real native export proof PR #24

These integrations do not mean all KerniQ actions are AgentFuse-protected. Patch, Git, MCP, browser actions, arbitrary direct IPC, arbitrary file writes, arbitrary shell, and other unreviewed paths remain outside these bounded claims unless separately integrated and proven.

Latest External Threat-Model Proof: Hermes #53021

The current agent-harness-v1 head includes a standalone proof for the session-scoped deny-by-default terminal allowlist threat model described in NousResearch/hermes-agent#53021.

It models that policy through the public Runtime Guard API and verifies:

• a matching skill-script command can reach the protected in-memory handler;
• a non-allowlisted command is blocked before dispatch;
• compound shell-control syntax is blocked before dispatch;
• retrying the same blocked action keeps the same canonical arguments hash and does not start the handler;
• deterministic re-evaluation of the same blocked action remains blocked;
• a changed action receives a different arguments hash; and
• safe receipts do not contain the original command text.

The proof does not patch Hermes, does not run a real shell, and does not claim Hermes restart persistence or a production Hermes integration.

References: proof README · proof script · regression tests · merged proof commit

LangGraph Adapter

AgentFuse includes an explicit installed-LangGraph ToolNode adapter. Blocked calls receive a terminal ToolMessage bound to the original tool-call ID; allowed handlers use the normal ToolNode execution path. Evidence receipts are available through adapter.receipts and adapter.receipt_for(tool_call_id).

This adapter does not make AgentFuse a universal LangGraph interceptor. Only the explicitly wrapped path is controlled.

Evidence Schema v0.1

AgentFuse Evidence Schema v0.1 represents a blocked tool call as a completed policy decision with non-execution evidence, not as a failed physical tool execution.

The schema keeps decision and execution as separate lifecycle facts. Safe evidence can retain tool-call identity, policy resolution, reason codes, execution state, and digests without including raw arguments, raw paths, environment variables, request bodies, credentials, or other sensitive payloads by default.

Provider-neutral denial regression fixtures are available at examples/trial/denial_lifecycle_regression_fixtures/.

Historical Evidence Archive

Earlier frozen proof lines remain valid historical evidence; they are not the current package version.

Key checkpoints:

• v3.4.2 real LangChain multi-tool selective interception result review
• v3.5.2 real langgraph_bigtool.create_agent() API wiring demo
• AgentFuse Public Decision API 3.6.0
• AgentFuse Consumer Integration Contract 3.6.1
• AgentFuse Cross-Adapter Conformance Kit 3.6.2
• AgentFuse Integration Result Review and Freeze 3.6.3
• AgentFuse Multi-Runtime Integration Package 3.7.0
• AgentFuse Five-Minute Integration Trial 3.7.1
• AgentFuse Compatibility Matrix and CI 3.7.2
• AgentFuse protocol package index
• Development roadmap
• Documentation directory

The historical v3.5.2 demo remains the latest historical langgraph_bigtool.create_agent() wiring checkpoint. It builds a guarded registry but does not compile, invoke, or stream that historical graph and makes no provider, database, SQL, credential, or production-runtime claim.

What AgentFuse Does Not Claim

AgentFuse is alpha/experimental infrastructure and does not claim:

• production readiness, certification, enterprise compliance, or universal side-effect prevention;
• process sandboxing, network firewalling, descendant-process containment, or malware detection;
• interception of execution paths that do not route through an integrated guard or adapter;
• intrinsic understanding of whether an action is dangerous, correct, authorized, or appropriate for a business;
• that every KerniQ action is protected by AgentFuse;
• that the Hermes #53021 proof is a production Hermes integration; or
• that historical evidence automatically proves arbitrary real-world agent protection.

A real integrating application must still design its own trustworthy action identities, approvals, policy context, durable lifecycle, execution boundary, recovery semantics, and defense-in-depth controls.

Feedback Wanted

Feedback is especially useful from developers building agent runtimes, tool gateways, approval systems, or side-effect-capable agent products.

Useful feedback includes:

• whether the evaluate() decision-only contract is straightforward to integrate into an existing Action Runtime;
• whether the responsibility split between application, adapter, AgentFuse, and physical executor is clear;
• whether the safe evidence vocabulary is sufficient for durable lifecycle recording;
• real execution-boundary threat models similar to Hermes #53021 that can be reduced to a bounded reproducible proof; and
• results from anyone willing to try RuntimeGuard in a real but controlled integration.

Discussion or interest alone is not treated as successful runtime adoption without an actual integration or trial result.

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.