Harnest Extension lifecycle

A Harnest Extension participates in three lifecycle layers:

Layer	Authoring location	Lifetime
SDK startup and shutdown	`Extension.start()` and `Extension.stop()` in `extension.py`	Application process
Typed access	`Extension.create_context()`	One managed invocation
Harnest hooks and factories	`extensions/<name>/lifecycle/*/.py`	The lifecycle phase declared by each decorator

The extension manifest must project lifecycle files through contributes.lifecycle and declare every Harnest capability those files use. Path declaration makes content visible to the compiler; capabilities authorize what that content may do. Neither grants access to undeclared runtime internals. Storage authorities start first. Harnest then calls Extension.start() in dependency order, followed by contributed @lifecycle.resource factories. Shutdown closes extension resources before calling Extension.stop() in reverse dependency order, then closes storage. ExtensionStartContext therefore exposes only already-live named custom storage and declared continuations, not arbitrary lifecycle resources or invocation credentials.

Declare and implement a hook

apiVersion: harnest.dev/v1alpha1
kind: Extension
metadata:
  name: warehouse
  version: 1.0.0
runtime:
  entrypoint: extension:extension
contributes:
  lifecycle: [lifecycle/]
capabilities:
  - lifecycle.tool

from harnest import lifecycle


@lifecycle.tool.before(order=-50)
async def restrict_warehouse_writes(context, request):
    """Require approved naming for model-selected warehouse writes."""

    # This extension owns policy only for the write tools it contributes.
    if context.tool_name.startswith("warehouse_write_"):
        return context.finish({"error": "use_an_approved_write_tool"})
    return context.next()

Application-owned and extension-owned lifecycle files form one globally validated lifecycle. Lower order values run first. Extension dependency order and source location break ties. Duplicate singleton authorities or named resources fail compilation rather than shadowing one another.

Choose a declared capability

Manifest capability	Contribution from the extension
`lifecycle.agent`, `.model`, `.tool`, `.mcp`, `.http`, `.skills`	Portable interception and dynamic skill sources
`context.resources`, `.credentials`, `.continuations`, `.storage`, `.assets`, `.session`, `.skills`, `.mcp`	Scoped runtime access used by the extension
`content.tools`, `.mcp`, `.skills`, `.subagents`	Managed-mode content
`storage.sessions`, `.checkpoints`, `.assets`, `.custom`	Storage factories
`http.routes`	Application HTTP routes
`native.adk`, `native.langgraph`	Framework-native integration
`policy.output`, `telemetry.exporter`	Output policy or telemetry destinations

Declare only the rows the extension actually uses. Advanced mode still composes Harnest-owned boundaries, but it cannot intercept an opaque native path that bypasses Harnest.

Audit committed mutations

Wrap committed user- or agent-triggered writes with extension_mutation(...). It emits correlated, payload-free OTEL audit events without recording arguments, credentials, or results:

extensions/warehouse/extension.py

from harnest.extensions import extension_mutation


async def _create_export(self, query_id: str):
    """Audit the committed SDK mutation without exposing its payload."""

    async with extension_mutation("warehouse", "export.create", trigger="agent"):
        return await self._client.create_export(query_id)

For external work that must survive a replica stopping, declare context.continuations and follow Durable execution. The extension persists bounded continuation metadata; it does not resume a suspended Python process.

Use the extension

Call the bounded public API from an Agent Tool or other trusted invocation code.

Overview

Get started

Guides

Harnest Extension lifecycle

Declare and implement a hook

Choose a declared capability

Audit committed mutations

Use the extension

​Declare and implement a hook

​Choose a declared capability

​Audit committed mutations

Use the extension

Declare and implement a hook

Choose a declared capability

Audit committed mutations