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

List lifecycle files in contributes.lifecycle and declare the capabilities they use. Both are required. 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

Create extensions/warehouse/extension.yaml

extensions/warehouse/extension.yaml

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

Create extensions/warehouse/lifecycle/tool_policy.py

extensions/warehouse/lifecycle/tool_policy.py

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()

Root and extension lifecycle files share one ordering: order, then dependency order, then source location. Duplicate singleton authorities or named resources fail compilation.

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

Harnest Studio

Guides

API reference

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