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.12.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.12.0
File Size Uploaded Provenance Actions
fusion_harness-0.12.0.tar.gz 101.2 kB With provenance Details for fusion_harness-0.12.0.tar.gz

Built distribution (wheel)

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

Total release size: 184.1 kB

Release files / fusion_harness-0.12.0.tar.gz

Download URL fusion_harness-0.12.0.tar.gz
Size 101.2 kB
Tags Source
SHA-256 checksum
How to use checksums
b0214622e4fb08a8d01ab3d4934b29271563d6f0f11645650761f1d4f4a3e93f
BLAKE2b-256 checksum
How to use checksums
9d64cdef7d7b3fa38d9984ef2949d563b120d9812d0381fedd60ffd2658deccf
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 14, 2026.

Transparency log

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

Download URL fusion_harness-0.12.0-py3-none-any.whl
Size 82.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6d072d5cdfd607b57cd9f6002146a5c28d7bdd0656696da4b19b801c16b61670
BLAKE2b-256 checksum
How to use checksums
acdfd09de7b6f9c1ac2667e6a9db5f6bd9e0f6dea6011c48fe3069a96f078e9a
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 14, 2026.

Transparency log

Security for fusion-harness 0.12.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.12.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 14, 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.12.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