Skip to main content

doc_id: fusion-harness/readme product: fusion-harness class: platform entry: developer doc_type: readme title: { zh: "fusion-harness 总览", en: "fusion-harness" } audience: developer status: draft version: 0.3.0 updated: 2026-11-07 owner: "@dahai" source_of_truth:

  • README.md

fusion-harness

Canonical agent harness kernel for the Fusion ecosystem: budget funnels, lifecycle hooks, permission engine, and context compaction. Pure stdlib, zero dependencies.

Consumers

  • fusion-agent-studio and fusion-cowork import this package directly (hard dependency — pip install -e fusion-harness; no in-tree fallback copies).
  • fusion-code (TypeScript) keeps its own implementation held to the same kernel contract by parity tests — cross-language runtime sharing is not the goal; contract conformance is.

The behavior contract for all runtimes lives in docs/contract.md. Architecture decisions are recorded as ADRs; see ADR 0001: the composition unit stays service-level, in-process everything-is-a-plugin is rejected, and the kernel commits to three adopted disciplines (event log, segmented pipeline, fail-closed approval).

Modules

  • fusion_harness.funnels — LLMFunnel, ToolFunnel, LifecycleBus (budget enforcement + lifecycle events)
  • fusion_harness.permissions — PermissionEngine (deny-first permission checks) + ConfirmationPolicy tiers and the deterministic score_tool_risk() bands, evaluated inside the engine (issue #9)
  • fusion_harness.hooks — HookEngine (lifecycle hook registry + dispatch)
  • fusion_harness.compactor — Compactor (context window compaction with retention)
  • fusion_harness.pipeline — ToolPipeline five-stage segmented tool execution: pre-execute waterfall, identity-protected monotonic guards, one-shot fail-closed approval, around-dispatch timeout/retry, post-execute waterfall — ending in a frozen ToolResult (issue #5)
  • fusion_harness.session_log — SessionEventLog durable append-only, schema-versioned, replayable session event log; live LifecycleEvents are structurally rejected (issue #4)

Security defaults (0.2.0, breaking)

Permission enforcement is fail-closed by default: a ToolFunnel without a wired PermissionEngine denies every tool call. Headless/CI deployments opt out explicitly:

export FUSION_FUNNEL_PERMISSIONS=off   # or FUSION_FUNNEL_REQUIRE_PERMISSIONS=0

Every call skipped this way logs permission enforcement DISABLED via ... — no deployment is silently unarmed. See docs/contract.md §5 for the full environment variable table.

Install

From PyPI:

pip install fusion-harness

From source (development):

pip install -e ".[test]"

Releases are published by CI on tag push (.github/workflows/release.yml) via PyPI trusted publishing.

Usage

from fusion_harness import Compactor, LLMFunnel, LifecycleBus, PermissionEngine, ToolFunnel

Test

pytest tests/        # unit coverage per module: funnels, permissions, hooks, compactor

The suite is the executable form of the contract: dangerous-pattern denies, layered rule precedence, fail-closed hook semantics, compaction levels, and the enforcement default flip. Consumer repos' CI (agent-studio, cowork) is the downstream detector for hidden passthrough assumptions.

License

Same license as the fusion monorepo.

Metadata

Release files for fusion-harness 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fusion-harness 0.6.0
File Size Uploaded Provenance Actions
fusion_harness-0.6.0.tar.gz 58.7 kB With provenance Details for fusion_harness-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fusion-harness 0.6.0
File Interpreter ABI Platform Actions
fusion_harness-0.6.0-py3-none-any.whl Python 3 none any Details for fusion_harness-0.6.0-py3-none-any.whl

Total release size: 107.0 kB

Release files / fusion_harness-0.6.0.tar.gz

Download URL fusion_harness-0.6.0.tar.gz
Size 58.7 kB
Tags Source
SHA-256 checksum
How to use checksums
0b08391a3868edfc3c310144f43fa08b3fb01ca52dd16781323a3c1a6a44ada9
BLAKE2b-256 checksum
How to use checksums
2260eb2ea854dc51a8a05369e90eca6cc0bf0864c622ad183892453e87b281d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / fusion_harness-0.6.0-py3-none-any.whl

Download URL fusion_harness-0.6.0-py3-none-any.whl
Size 48.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b8174a27abfa56bea5fe9cc574bd9a9e9530ffda9614f7be73086e5984050aea
BLAKE2b-256 checksum
How to use checksums
4d2ff321ce6156affab3a293f6a05e607a29fe74ce1b115d6f1ab408a7fbfd5b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for fusion-harness 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fusion_harness-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page