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.24.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.24.0
File Size Uploaded Provenance Actions
fusion_harness-0.24.0.tar.gz 228.4 kB With provenance Details for fusion_harness-0.24.0.tar.gz

Built distribution (wheel)

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

Total release size: 395.4 kB

Release files / fusion_harness-0.24.0.tar.gz

Download URL fusion_harness-0.24.0.tar.gz
Size 228.4 kB
Tags Source
SHA-256 checksum
How to use checksums
cf7c26ba510b54fc50ac1ccb1cfc0a60bac412bd40df260c6b4ad853b6330222
BLAKE2b-256 checksum
How to use checksums
c02aec1913b7c2f32f174fb56760c596de9b6d2d19de3a816e8a3cfa662ddfd6
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 19, 2026.

Transparency log

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

Download URL fusion_harness-0.24.0-py3-none-any.whl
Size 167.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7ad2d03138afe16592bb5415b4bdc9ebbde606bb69676d3fdd9647c3a321a172
BLAKE2b-256 checksum
How to use checksums
1f2da683f8a1fc2ff8d6f1f331bd9cf605a32b4b4af10fadb2439ad64c200c72
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 19, 2026.

Transparency log

Security for fusion-harness 0.24.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.24.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 19, 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.24.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