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.9.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.9.0
File Size Uploaded Provenance Actions
fusion_harness-0.9.0.tar.gz 76.8 kB With provenance Details for fusion_harness-0.9.0.tar.gz

Built distribution (wheel)

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

Total release size: 139.8 kB

Release files / fusion_harness-0.9.0.tar.gz

Download URL fusion_harness-0.9.0.tar.gz
Size 76.8 kB
Tags Source
SHA-256 checksum
How to use checksums
620421adc4d326c143d4e44576c68ca1a27e9df08ef339a970059b9b9c4522e1
BLAKE2b-256 checksum
How to use checksums
d080712e2079ee489d50bf0d14ef512adc2996af50613d534a7f3fbecfbcdfb0
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 12, 2026.

Transparency log

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

Download URL fusion_harness-0.9.0-py3-none-any.whl
Size 63.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
819fe4d17d6b83c4908786552829ed75da6bab943bfef8e85cbae61310ec59b4
BLAKE2b-256 checksum
How to use checksums
65b991a2268d6f326b5ad9d6fb558d52c991e8f6d4eef0366a7c55493e03b7dd
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 12, 2026.

Transparency log

Security for fusion-harness 0.9.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.9.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 12, 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.9.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