Use a Harnest Extension

A project-local Harnest Extension is discovered from extensions/<name>/extension.yaml. You do not add it to a central registry or manually attach it to the root agent. From the agent folder, install a verified public PyPI wheel by its short slug or full distribution name:

harnest extensions install warehouse
# Equivalent: harnest extensions install harnest-extension-warehouse
harnest env sync .

To review and test an unpublished extension, install its local source tree instead:

harnest extensions install ../harnest-extension-warehouse
harnest env sync .

For a PyPI install, Harnest accepts a universal py3-none-any wheel and validates the manifest, wheel metadata, digest, entry point, and package layout without importing extension code. Platform- or ABI-specific wheels are not installed. For local source, it validates the manifest and layout plus any available project identity and version metadata. Both paths materialize the complete package into extensions/<manifest-name> through a staged replacement and preserve its internal paths. Compilation projects only directories listed in contributes; it does not scatter their files into the agent root. Harnest refuses an existing extension unless you pass --force. Review same-process extension code and its declared capabilities before installation; installing changes dependency inputs, so refresh harnest-runtime.lock with harnest env sync .. Published wheels may declare dependencies on Harnest or its framework packages. During installation, Harnest omits those compiler-owned requirements from the materialized project and supplies its pinned runtime versions instead. Extension-owned dependencies remain in the root environment solve. Locally authored extensions must not redeclare compiler-owned packages. After compilation, Harnest exposes the extension module as harnest.extensions.<name>. Import the singleton from a discovered Agent Tool and call its bounded API:

tools/query_warehouse.py

from harnest.extensions.warehouse import extension as warehouse
from harnest.agent import tool


@tool
async def query_warehouse(statement: str) -> list[dict]:
    """Query the configured warehouse through its Harnest Extension."""

    return await warehouse.query(statement)

The call runs inside a managed invocation, so warehouse.context resolves the typed WarehouseContext created for that request. Retaining it after the invocation ends fails closed.

Resolve the typed context explicitly

Trusted application code can ask Harnest for the same invocation-scoped view:

lib/warehouse_service.py

from harnest import context
from harnest.extensions.warehouse import WarehouseContext


async def run_query(statement: str) -> list[dict]:
    """Resolve the warehouse capability without exposing its SDK client."""

    warehouse = context.extensions("warehouse", WarehouseContext)
    return await warehouse.query(statement)

Keep application clients and connection pools private on the singleton. Expose domain operations through the typed context instead of returning the raw SDK object.

Find published extensions

Search public PyPI for compatible harnest-extension-* packages:

harnest extensions search warehouse

Search verifies package naming, one harnest.extensions entry point, the bundled extension.yaml and extension.py, release identity, and the published wheel digest without importing package code. official means Fused controls and explicitly recognizes that package name; community means only that the wheel satisfies the structural contract. Neither label is a security review.

Search does not install an extension, and pip install alone does not register one with an agent project. Use harnest extensions install <slug-or-project> to verify and materialize a published wheel, then run harnest env sync before compiling.

Create your own extension

Define the local manifest, singleton, typed context, and dependencies.

Use extension lifecycle

Add only the hooks and factories declared by the manifest.

Overview

Get started

Guides

Use a Harnest Extension

Resolve the typed context explicitly

Find published extensions

Create your own extension

Use extension lifecycle

​Resolve the typed context explicitly

​Find published extensions

Create your own extension

Use extension lifecycle

Resolve the typed context explicitly

Find published extensions