> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# harnest.lifecycle

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## HTTP agent principal grants

`@lifecycle.http.agent_principal` registers one sync or async function that receives a `ConnectionContext` and an `AuthPrincipal`. Return an `AgentRuntimePrincipal` to grant permissions or `None` to deny the invocation. See [Grant permissions on built-in routes](https://usefused.com/docs/harnest/runtime/agent-runtime-principals.md#grant-permissions-on-built-in-routes).

## Hook control flow

| Return | Effect |
| - | - |
| `context.next()` | Continue unchanged |
| `context.next(replacement)` | Pass a replacement to the next stage |
| `context.finish(result)` | Stop the chain with a final result |

## Exports

| Name | Kind |
| - | - |
| [`CoverageLevel`](#coveragelevel) | Class |
| [`DROP_EVENT`](#drop_event) | Namespace |
| [`EvalCaptureOptions`](#evalcaptureoptions) | Class |
| [`Finish`](#finish) | Class |
| [`LifecycleContext`](#lifecyclecontext) | Class |
| [`LifecycleCoverage`](#lifecyclecoverage) | Class |
| [`LifecycleListener`](#lifecyclelistener) | Class |
| [`LifecycleRegistration`](#lifecycleregistration) | Class |
| [`ModelCallRequest`](#modelcallrequest) | Class |
| [`ModelCallResponse`](#modelcallresponse) | Class |
| [`ModelLifecycleContext`](#modellifecyclecontext) | Class |
| [`ModelMessage`](#modelmessage) | Class |
| [`Next`](#next) | Class |
| [`TransitionContext`](#transitioncontext) | Class |
| [`adk_plugin`](#adk_plugin) | Function |
| [`agent`](#agent) | Namespace |
| [`authenticate`](#authenticate) | Namespace |
| [`coverage`](#coverage) | Function |
| [`credential_provider`](#credential_provider) | Namespace |
| [`eval_capture_options`](#eval_capture_options) | Function |
| [`evals`](#evals) | Namespace |
| [`http`](#http) | Namespace |
| [`http_routes`](#http_routes) | Namespace |
| [`langgraph_middleware`](#langgraph_middleware) | Function |
| [`lifecycle_coverage`](#lifecycle_coverage) | Function |
| [`mcp`](#mcp) | Namespace |
| [`model`](#model) | Namespace |
| [`output_policy`](#output_policy) | Namespace |
| [`registrations_for`](#registrations_for) | Function |
| [`resource`](#resource) | Namespace |
| [`session`](#session) | Namespace |
| [`skills`](#skills) | Namespace |
| [`storage`](#storage) | Namespace |
| [`telemetry_exporter`](#telemetry_exporter) | Namespace |
| [`tool`](#tool) | Namespace |

## CoverageLevel

Describe how completely Harnest governs one runtime boundary.

```python theme={null}
CoverageLevel(*values)
```

| Member | Value |
| - | - |
| `FULL` | `'full'` |
| `WRAPPED_ONLY` | `'wrapped-only'` |
| `BEST_EFFORT` | `'best-effort'` |
| `FRAMEWORK_OWNED` | `'framework-owned'` |
| `UNAVAILABLE` | `'unavailable'` |

> [accordion] Example
>
> ```python theme={null}
> from harnest.lifecycle import CoverageLevel
>
> value = CoverageLevel.FULL
> ```

## DROP\_EVENT

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
>
> value = lifecycle.DROP_EVENT
> ```

## EvalCaptureOptions

Authored capture settings; `None` defers to the environment, then defaults.

```python theme={null}
EvalCaptureOptions(store: str, sample_rate: float | None = None) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `store` | `str` | `—` |
| `sample_rate` | `float \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `store` | `str` | Required |
> | `sample_rate` | `float \| None` | `None` |
>
> ```python theme={null}
> from harnest.lifecycle import EvalCaptureOptions
>
> options = EvalCaptureOptions(store=...)
> ```

## Finish

Complete an intercepting lifecycle stage without calling later work.

```python theme={null}
Finish(result: ResultT) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `result` | `ResultT` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `result` | `ResultT` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import Finish
>
> finish = Finish(result=...)
> ```

## LifecycleContext

Portable invocation context shared by listeners for one execution.

```python theme={null}
LifecycleContext(
    framework: str,
    agent_name: str,
    invocation_id: str,
    user_id: str,
    session_id: str,
    metadata: Mapping[str, Any] = ...,
    attributes: MutableMapping[str, Any] = ...,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `framework` | `str` | `—` |
| `agent_name` | `str` | `—` |
| `invocation_id` | `str` | `—` |
| `user_id` | `str` | `—` |
| `session_id` | `str` | `—` |
| `metadata` | `Mapping[str, Any]` | `dict()` |
| `attributes` | `MutableMapping[str, Any]` | `dict()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `framework` | `str` | Required |
> | `agent_name` | `str` | Required |
> | `invocation_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `metadata` | `Mapping[str, Any]` | `...` |
> | `attributes` | `MutableMapping[str, Any]` | `...` |
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleContext
>
> context = LifecycleContext(
>     framework=...,
>     agent_name=...,
>     invocation_id=...,
>     user_id=...,
>     session_id=...,
> )
> ```

### LifecycleContext.next

```python theme={null}
LifecycleContext.next(replacement: Any = UNCHANGED) -> Next[Any]
```

Continue normally or pass a replacement to the next interceptor.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `replacement` | `Any` | `UNCHANGED` |
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleContext
>
> context: LifecycleContext
> result = context.next()
> ```

### LifecycleContext.finish

```python theme={null}
LifecycleContext.finish(result: ResultT) -> Finish[ResultT]
```

Return a final value without advancing to later execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `result` | `ResultT` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleContext
>
> context: LifecycleContext
> result = context.finish(result=...)
> ```

## LifecycleCoverage

Stable report of lifecycle boundaries Harnest can actually guarantee.

```python theme={null}
LifecycleCoverage(
    framework: Literal['adk', 'langgraph'],
    mode: Literal['managed', 'advanced'],
    application: CoverageLevel,
    http: CoverageLevel,
    invocation: CoverageLevel,
    credentials: CoverageLevel,
    session: CoverageLevel,
    assets: CoverageLevel,
    model: CoverageLevel,
    tool: CoverageLevel,
    mcp: CoverageLevel,
    agent: CoverageLevel,
    subagent: CoverageLevel,
    checkpoint: CoverageLevel,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `framework` | `Literal['adk', 'langgraph']` | `—` |
| `mode` | `Literal['managed', 'advanced']` | `—` |
| `application` | `CoverageLevel` | `—` |
| `http` | `CoverageLevel` | `—` |
| `invocation` | `CoverageLevel` | `—` |
| `credentials` | `CoverageLevel` | `—` |
| `session` | `CoverageLevel` | `—` |
| `assets` | `CoverageLevel` | `—` |
| `model` | `CoverageLevel` | `—` |
| `tool` | `CoverageLevel` | `—` |
| `mcp` | `CoverageLevel` | `—` |
| `agent` | `CoverageLevel` | `—` |
| `subagent` | `CoverageLevel` | `—` |
| `checkpoint` | `CoverageLevel` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `framework` | `Literal['adk', 'langgraph']` | Required |
> | `mode` | `Literal['managed', 'advanced']` | Required |
> | `application` | `CoverageLevel` | Required |
> | `http` | `CoverageLevel` | Required |
> | `invocation` | `CoverageLevel` | Required |
> | `credentials` | `CoverageLevel` | Required |
> | `session` | `CoverageLevel` | Required |
> | `assets` | `CoverageLevel` | Required |
> | `model` | `CoverageLevel` | Required |
> | `tool` | `CoverageLevel` | Required |
> | `mcp` | `CoverageLevel` | Required |
> | `agent` | `CoverageLevel` | Required |
> | `subagent` | `CoverageLevel` | Required |
> | `checkpoint` | `CoverageLevel` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleCoverage
>
> coverage = LifecycleCoverage(
>     framework=...,
>     mode=...,
>     application=...,
>     http=...,
>     invocation=...,
>     credentials=...,
>     session=...,
>     assets=...,
>     model=...,
>     tool=...,
>     mcp=...,
>     agent=...,
>     subagent=...,
>     checkpoint=...,
> )
> ```

### LifecycleCoverage.stage

```python theme={null}
LifecycleCoverage.stage(name: str) -> CoverageLevel
```

Return one declared stage without exposing implementation state.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleCoverage
>
> coverage: LifecycleCoverage
> level = coverage.stage(name=...)
> ```

### LifecycleCoverage.report

```python theme={null}
LifecycleCoverage.report() -> Mapping[str, str]
```

Return an immutable JSON-compatible diagnostics report.

> [accordion] Example
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleCoverage
>
> coverage: LifecycleCoverage
> result = coverage.report()
> ```

### LifecycleCoverage.with\_overrides

```python theme={null}
LifecycleCoverage.with_overrides(overrides: Mapping[str, CoverageLevel]) -> 'LifecycleCoverage'
```

Record adapter-observed limits without changing mode defaults.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `overrides` | `Mapping[str, CoverageLevel]` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleCoverage
>
> coverage: LifecycleCoverage
> coverage = coverage.with_overrides(overrides=...)
> ```

## LifecycleListener

One discovered callback with a deterministic source identity.

```python theme={null}
LifecycleListener(
    phase: str,
    callback: Callable[..., Any],
    order: int,
    relative_path: str,
    line: int,
    function_name: str,
    framework: str | None = None,
    context_name: str | None = None,
    registration_name: str | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `phase` | `str` | `—` |
| `callback` | `Callable[..., Any]` | `—` |
| `order` | `int` | `—` |
| `relative_path` | `str` | `—` |
| `line` | `int` | `—` |
| `function_name` | `str` | `—` |
| `framework` | `str \| None` | `None` |
| `context_name` | `str \| None` | `None` |
| `registration_name` | `str \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `phase` | `str` | Required |
> | `callback` | `Callable[..., Any]` | Required |
> | `order` | `int` | Required |
> | `relative_path` | `str` | Required |
> | `line` | `int` | Required |
> | `function_name` | `str` | Required |
> | `framework` | `str \| None` | `None` |
> | `context_name` | `str \| None` | `None` |
> | `registration_name` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleListener
>
> listener = LifecycleListener(
>     phase=...,
>     callback=...,
>     order=...,
>     relative_path=...,
>     line=...,
>     function_name=...,
> )
> ```

### LifecycleListener.identity

Return the stable identity used to order and deduplicate listeners.

> [accordion] Example
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleListener
>
> listener: LifecycleListener
> value = listener.identity
> ```

## LifecycleRegistration

Metadata attached by one lifecycle decorator.

```python theme={null}
LifecycleRegistration(phase: str, order: int, framework: str | None = None, name: str | None = None) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `phase` | `str` | `—` |
| `order` | `int` | `—` |
| `framework` | `str \| None` | `None` |
| `name` | `str \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `phase` | `str` | Required |
> | `order` | `int` | Required |
> | `framework` | `str \| None` | `None` |
> | `name` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.lifecycle import LifecycleRegistration
>
> registration = LifecycleRegistration(phase=..., order=...)
> ```

## ModelCallRequest

Portable model input that a listener may replace or short-circuit.

```python theme={null}
ModelCallRequest(model: str | None, messages: tuple[ModelMessage, ...]) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `model` | `str \| None` | `—` |
| `messages` | `tuple[ModelMessage, ...]` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `model` | `str \| None` | Required |
> | `messages` | `tuple[ModelMessage, ...]` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import ModelCallRequest
>
> request = ModelCallRequest(model=..., messages=...)
> ```

## ModelCallResponse

Portable visible model output.

```python theme={null}
ModelCallResponse(text: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `text` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `text` | `str` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import ModelCallResponse
>
> response = ModelCallResponse(text=...)
> ```

## ModelLifecycleContext

Stable provider-neutral facts associated with one model call.

```python theme={null}
ModelLifecycleContext(
    framework: str,
    agent_name: str | None = None,
    invocation_id: str | None = None,
    user_id: str | None = None,
    session_id: str | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `framework` | `str` | `—` |
| `agent_name` | `str \| None` | `None` |
| `invocation_id` | `str \| None` | `None` |
| `user_id` | `str \| None` | `None` |
| `session_id` | `str \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `framework` | `str` | Required |
> | `agent_name` | `str \| None` | `None` |
> | `invocation_id` | `str \| None` | `None` |
> | `user_id` | `str \| None` | `None` |
> | `session_id` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.lifecycle import ModelLifecycleContext
>
> context = ModelLifecycleContext(framework=...)
> ```

### ModelLifecycleContext.next

```python theme={null}
ModelLifecycleContext.next(replacement: Any = UNCHANGED) -> Next[Any]
```

Continue normally or pass a replacement to the next interceptor.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `replacement` | `Any` | `UNCHANGED` |
>
> ```python theme={null}
> from harnest.lifecycle import ModelLifecycleContext
>
> context: ModelLifecycleContext
> result = context.next()
> ```

### ModelLifecycleContext.finish

```python theme={null}
ModelLifecycleContext.finish(result: ResultT) -> Finish[ResultT]
```

Return a final value without advancing to later execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `result` | `ResultT` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import ModelLifecycleContext
>
> context: ModelLifecycleContext
> result = context.finish(result=...)
> ```

## ModelMessage

One provider-independent text message in a model call.

```python theme={null}
ModelMessage(role: str, text: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `role` | `str` | `—` |
| `text` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `role` | `str` | Required |
> | `text` | `str` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import ModelMessage
>
> message = ModelMessage(role=..., text=...)
> ```

## Next

Continue a lifecycle chain, optionally with a replacement value.

```python theme={null}
Next(value: ValueT | _Unchanged = UNCHANGED) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `value` | `ValueT \| _Unchanged` | `UNCHANGED` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `value` | `ValueT \| _Unchanged` | `UNCHANGED` |
>
> ```python theme={null}
> from harnest.lifecycle import Next
>
> next_value = Next()
> ```

### Next.replaces

Report whether the next stage should receive a replacement value.

> [accordion] Example
>
> ```python theme={null}
> from harnest.lifecycle import Next
>
> next_value: Next
> value = next_value.replaces
> ```

## TransitionContext

Give typed lifecycle contexts one consistent control-flow vocabulary.

```python theme={null}
TransitionContext()
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.lifecycle import TransitionContext
>
> context = TransitionContext()
> ```

### TransitionContext.next

```python theme={null}
TransitionContext.next(replacement: Any = UNCHANGED) -> Next[Any]
```

Continue normally or pass a replacement to the next interceptor.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `replacement` | `Any` | `UNCHANGED` |
>
> ```python theme={null}
> from harnest.lifecycle import TransitionContext
>
> context: TransitionContext
> result = context.next()
> ```

### TransitionContext.finish

```python theme={null}
TransitionContext.finish(result: ResultT) -> Finish[ResultT]
```

Return a final value without advancing to later execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `result` | `ResultT` | Required |
>
> ```python theme={null}
> from harnest.lifecycle import TransitionContext
>
> context: TransitionContext
> result = context.finish(result=...)
> ```

## adk\_plugin

Register a native ADK plugin factory at the lifecycle boundary.

```python theme={null}
adk_plugin(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.adk_plugin
> def plugin():
>     ...  # return an ADK BasePlugin
> ```

## agent

Name invocation hooks by their agent lifecycle responsibility.

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
> ```

### agent.before

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
agent.before(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.agent.before
> async def check_request(context, request):
>     return context.next()
> ```

### agent.after

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
agent.after(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.agent.after
> async def record_result(context, result):
>     return context.next()
> ```

### agent.on\_event

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
agent.on_event(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.agent.on_event
> async def observe_event(context, event):
>     return context.next()
> ```

### agent.on\_error

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
agent.on_error(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.agent.on_error
> async def report_failure(context, error):
>     return context.next()
> ```

## authenticate

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
authenticate(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.authenticate
> async def authenticate(connection, principal):
>     ...
> ```

## coverage

Build conservative defaults and apply adapter-observed coverage limits.

```python theme={null}
coverage(framework: str, mode: str, *, overrides: Mapping[str, CoverageLevel] | None = None) -> LifecycleCoverage
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `framework` | `str` | Required |
> | `mode` | `str` | Required |
> | `overrides` | `Mapping[str, CoverageLevel] \| None` | `None` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> coverage = lifecycle.coverage(framework=..., mode=...)
> ```

## credential\_provider

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
credential_provider(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.credential_provider
> def credential_provider():
>     ...
> ```

## eval\_capture\_options

Return capture options attached by `@lifecycle.evals.capture`.

```python theme={null}
eval_capture_options(function: Any) -> EvalCaptureOptions | None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `Any` | Required |
>
> ```python theme={null}
> from harnest import lifecycle
>
> options = lifecycle.eval_capture_options(function=...)
> ```

## evals

Production eval improvement hooks, valid only in `lifecycle/evals_improvement.py`.

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
> ```

### evals.capture

```python theme={null}
evals.capture(*, store: str, sample_rate: float | None = None) -> Callable[[_Hook], _Hook]
```

Select finished invocations for structure-only or team-redacted capture.

`store` names a `@lifecycle.storage.custom` provider implementing
`harnest.eval_capture.CaptureStore`. `sample_rate` additionally
captures that fraction of invocations the rule rejects.
Content is omitted unless `@lifecycle.evals.redact` is registered.
That hook takes and returns one `CaptureRecord`; any other return
value drops the capture. Harnest does not detect personal data.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `store` | `str` | Required |
> | `sample_rate` | `float \| None` | `None` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.evals.capture(store="captures", sample_rate=0.05)
> def should_capture(event) -> bool:
>     ...
> ```

### evals.redact

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
evals.redact(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.evals.redact
> def redact_capture(record):
>     ...
> ```

## http

Group server middleware hooks under the HTTP lifecycle boundary.

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
> ```

### http.scope

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
http.scope(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.http.scope
> def request_scope(context, request):
>     ...  # return an async context manager
> ```

### http.before

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
http.before(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.http.before
> async def check_http_request(context, request):
>     return context.next()
> ```

### http.after

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
http.after(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.http.after
> def response(context, head):
>     return context.next()
> ```

### http.on\_error

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
http.on_error(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.http.on_error
> async def http_failed(context, error):
>     return context.next()
> ```

### http.agent\_principal

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
http.agent_principal(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
> from harnest.agent import AgentRuntimePrincipal
> from harnest.auth import AuthPrincipal, ConnectionContext
>
> @lifecycle.http.agent_principal
> def grant(
>     connection: ConnectionContext,
>     principal: AuthPrincipal,
> ) -> AgentRuntimePrincipal:
>     permissions = set()
>     if principal.claims.get("can_refund") is True:
>         permissions.add("refunds.write")
>     return AgentRuntimePrincipal.create(permissions=permissions)
> ```

## http\_routes

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
http_routes(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.http_routes
> def http_routes(agent):
>     ...  # return a FastAPI router
> ```

## langgraph\_middleware

Register a native LangGraph middleware factory at the lifecycle boundary.

```python theme={null}
langgraph_middleware(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.langgraph_middleware
> def middleware():
>     ...
> ```

## lifecycle\_coverage

Build conservative defaults and apply adapter-observed coverage limits.

```python theme={null}
lifecycle_coverage(
    framework: str,
    mode: str,
    *,
    overrides: Mapping[str, CoverageLevel] | None = None,
) -> LifecycleCoverage
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `framework` | `str` | Required |
> | `mode` | `str` | Required |
> | `overrides` | `Mapping[str, CoverageLevel] \| None` | `None` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> coverage = lifecycle.lifecycle_coverage(framework=..., mode=...)
> ```

## mcp

Group managed remote-tool hooks separately from transport ownership.

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
> ```

### mcp.before

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
mcp.before(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.mcp.before
> async def check_remote_call(context, request):
>     return context.next()
> ```

### mcp.after

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
mcp.after(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.mcp.after
> async def check_remote_result(context, result):
>     return context.next()
> ```

### mcp.on\_error

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
mcp.on_error(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.mcp.on_error
> async def remote_failed(context, error):
>     return context.next()
> ```

## model

Group provider-neutral model hooks under one authoring namespace.

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
> ```

### model.before

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
model.before(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.model.before
> async def check_prompt(context, request):
>     return context.next()
> ```

### model.after

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
model.after(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.model.after
> async def check_reply(context, response):
>     return context.next()
> ```

### model.on\_error

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
model.on_error(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.model.on_error
> async def model_failed(context, error):
>     return context.next()
> ```

## output\_policy

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
output_policy(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.output_policy
> def output_policy():
>     ...
> ```

## registrations\_for

Return every role attached to a possibly shared storage factory.

```python theme={null}
registrations_for(function: Any) -> tuple[LifecycleRegistration, ...]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `Any` | Required |
>
> ```python theme={null}
> from harnest import lifecycle
>
> result = lifecycle.registrations_for(function=...)
> ```

## resource

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
resource(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.resource
> async def catalog():
>     ...
> ```

## session

Observe committed sessions without participating in persistence.

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
> ```

### session.created

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
session.created(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.session.created
> async def session_created(info, session):
>     ...
> ```

## skills

Register named runtime catalogs independently of filesystem skills.

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
> ```

### skills.source

```python theme={null}
skills.source(name: str, *, order: int = 0) -> Callable[[_Hook], _Hook]
```

Declare one named provider queried only during managed execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `name` | `str` | Required | Name of the runtime skill catalog. |
> | `order` | `int` | `0` | — |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.skills.source("wex")
> def wex():
>     ...
> ```

## storage

Namespace storage roles while retaining distributed file discovery.

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
> ```

### storage.sessions

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
storage.sessions(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.storage.sessions
> def sessions():
>     ...  # return a session store
> ```

### storage.checkpoints

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
storage.checkpoints(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.storage.checkpoints
> def checkpoints():
>     ...  # return a checkpoint store
> ```

### storage.tasks

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
storage.tasks(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.storage.tasks
> def task_storage():
>     ...  # return a task store
> ```

### storage.cron

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
storage.cron(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.storage.cron
> def cron_storage():
>     ...  # return a cron store
> ```

### storage.memory

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
storage.memory(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.storage.memory
> def memory():
>     ...  # return a memory store
> ```

### storage.assets

```python theme={null}
storage.assets(name: str, *, order: int = 0) -> Callable[[_Hook], _Hook]
```

Declare one named asset authority assembled into the registry.

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `name` | `str` | Required | Asset store name. |
> | `order` | `int` | `0` | — |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.storage.assets("media")
> def media_assets():
>     ...
> ```

### storage.custom

```python theme={null}
storage.custom(name: str, *, order: int = 0) -> Callable[[_Hook], _Hook]
```

Declare lifecycle-owned application storage under an explicit name.

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `name` | `str` | Required | Name the store is looked up by. |
> | `order` | `int` | `0` | — |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.storage.custom("users")
> def users():
>     ...
> ```

## telemetry\_exporter

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
telemetry_exporter(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.telemetry_exporter
> def telemetry():
>     ...
> ```

## tool

Group portable tool interception under its first-class domain path.

> [accordion] Example
>
> ```python theme={null}
> from harnest import lifecycle
> ```

### tool.before

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
tool.before(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `function` | `_Hook \| None` | `None` | — |
> | `order` | `int` | `0` | Lower values run first. |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.tool.before(order=-100)
> async def check_tool(context, request):
>     return context.next()
> ```

### tool.after

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
tool.after(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.tool.after
> def tool_completed(context, result):
>     return context.next()
> ```

### tool.on\_error

Preserve authored hook signatures while attaching lifecycle metadata.

```python theme={null}
tool.on_error(function: _Hook | None = None, *, order: int = 0) -> _Hook | Callable[[_Hook], _Hook]
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `function` | `_Hook \| None` | `None` |
> | `order` | `int` | `0` |
>
> ```python theme={null}
> from harnest import lifecycle
>
> @lifecycle.tool.on_error
> def tool_failed(context, error):
>     return context.next()
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.