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.23.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.23.0
File Size Uploaded Provenance Actions
fusion_harness-0.23.0.tar.gz 203.7 kB With provenance Details for fusion_harness-0.23.0.tar.gz

Built distribution (wheel)

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

Total release size: 353.1 kB

Release files / fusion_harness-0.23.0.tar.gz

Download URL fusion_harness-0.23.0.tar.gz
Size 203.7 kB
Tags Source
SHA-256 checksum
How to use checksums
f41423689aaf73bf6c6eab8621a3ad2d03e5c1b8be3955f7f0ee0e72c05f2e9a
BLAKE2b-256 checksum
How to use checksums
ad4f920f641df7ce83f58010e2c563589c0e5b6ae0b15d097468ca0286a81d31
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.23.0-py3-none-any.whl

Download URL fusion_harness-0.23.0-py3-none-any.whl
Size 149.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
88a4d071f04f9b67d14a65439b66539b751d7490b54d04fa92ea03ba31a383a8
BLAKE2b-256 checksum
How to use checksums
5408bf73705626c5f9985cbeed23936061e7224289875962245510e80fcfb688
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.23.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.23.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.23.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