> ## 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.continuation

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

## Exports

| Name | Kind |
| - | - |
| [`ContinuationConflictError`](#continuationconflicterror) | Class |
| [`ContinuationError`](#continuationerror) | Class |
| [`ContinuationFailure`](#continuationfailure) | Class |
| [`ContinuationProvider`](#continuationprovider) | Class |
| [`ContinuationRecord`](#continuationrecord) | Class |
| [`ContinuationStatus`](#continuationstatus) | Value or type alias |
| [`ContinuationStore`](#continuationstore) | Class |
| [`ContinuationValidationError`](#continuationvalidationerror) | Class |
| [`ProviderPendingContinuation`](#providerpendingcontinuation) | Class |
| [`audit_continuation`](#audit_continuation) | Function |
| [`continuation_schema_id`](#continuation_schema_id) | Function |
| [`external_id_key`](#external_id_key) | Function |

## ContinuationConflictError

Raised when a continuation compare-and-swap condition changed.

> [accordion] Example
>
> ```python theme={null}
> from harnest.continuation import ContinuationConflictError
>
> try:
>     ...
> except ContinuationConflictError as error:
>     ...
> ```

## ContinuationError

Base error for external continuation ownership and persistence.

> [accordion] Example
>
> ```python theme={null}
> from harnest.continuation import ContinuationError
>
> try:
>     ...
> except ContinuationError as error:
>     ...
> ```

## ContinuationFailure

A provider-defined failure category without exception or payload text.

```python theme={null}
ContinuationFailure(code: str, retryable: bool = False) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `code` | `str` | `—` |
| `retryable` | `bool` | `False` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `code` | `str` | Required |
> | `retryable` | `bool` | `False` |
>
> ```python theme={null}
> from harnest.continuation import ContinuationFailure
>
> failure = ContinuationFailure(code=...)
> ```

## ContinuationProvider

Application/provider-bound facade supplied to trusted plugin code.

```python theme={null}
ContinuationProvider(store: ContinuationStore, *, application_id: str, provider: str) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `store` | `ContinuationStore` | Required |
> | `application_id` | `str` | Required |
> | `provider` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider = ContinuationProvider(store=..., application_id=..., provider=...)
> ```

### ContinuationProvider.name

Return the low-cardinality provider identity bound by the host.

> [accordion] Example
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> value = provider.name
> ```

### ContinuationProvider.suspend

```python theme={null}
async ContinuationProvider.suspend(
    *,
    user_id: str,
    session_id: str,
    run_id: str,
    external_id: str,
    capability: str,
    schema_id: str,
    resume: ResumeArtifact,
    principal_grants: PrincipalGrantSnapshot | None = None,
) -> ContinuationRecord
```

Atomically persist a wait and transition its owned run to waiting.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `run_id` | `str` | Required |
> | `external_id` | `str` | Required |
> | `capability` | `str` | Required |
> | `schema_id` | `str` | Required |
> | `resume` | `ResumeArtifact` | Required |
> | `principal_grants` | `PrincipalGrantSnapshot \| None` | `None` |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> record = await provider.suspend(
>     user_id=...,
>     session_id=...,
>     run_id=...,
>     external_id=...,
>     capability=...,
>     schema_id=...,
>     resume=...,
> )
> ```

### ContinuationProvider.lookup

```python theme={null}
async ContinuationProvider.lookup(external_id: str) -> ProviderPendingContinuation | None
```

Resolve one provider-owned external identity with an indexed lookup.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `external_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> continuation = await provider.lookup(external_id=...)
> ```

### ContinuationProvider.get

```python theme={null}
async ContinuationProvider.get(*, user_id: str, session_id: str, run_id: str, continuation_id: str) -> ContinuationRecord | None
```

Read one continuation only through its complete ownership scope.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `run_id` | `str` | Required |
> | `continuation_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> record = await provider.get(
>     user_id=...,
>     session_id=...,
>     run_id=...,
>     continuation_id=...,
> )
> ```

### ContinuationProvider.get\_pending

```python theme={null}
async ContinuationProvider.get_pending(
    *,
    user_id: str,
    session_id: str,
    run_id: str,
    continuation_id: str,
) -> ProviderPendingContinuation | None
```

Read provider-private identity through complete run ownership.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `run_id` | `str` | Required |
> | `continuation_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> continuation = await provider.get_pending(
>     user_id=...,
>     session_id=...,
>     run_id=...,
>     continuation_id=...,
> )
> ```

### ContinuationProvider.list\_pending

```python theme={null}
async ContinuationProvider.list_pending(*, after: str | None = None, limit: int = 100) -> Sequence[ProviderPendingContinuation]
```

Read one bounded indexed page for provider startup reconciliation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `after` | `str \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> result = await provider.list_pending()
> ```

### ContinuationProvider.complete

```python theme={null}
async ContinuationProvider.complete(
    *,
    user_id: str,
    session_id: str,
    run_id: str,
    external_id: str,
    schema_id: str,
    result: Any,
    validate: ContinuationValidator,
) -> ContinuationRecord
```

Validate provider output before committing its private result.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `run_id` | `str` | Required |
> | `external_id` | `str` | Required |
> | `schema_id` | `str` | Required |
> | `result` | `Any` | Required |
> | `validate` | `ContinuationValidator` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> record = await provider.complete(
>     user_id=...,
>     session_id=...,
>     run_id=...,
>     external_id=...,
>     schema_id=...,
>     result=...,
>     validate=...,
> )
> ```

### ContinuationProvider.fail

```python theme={null}
async ContinuationProvider.fail(
    *,
    user_id: str,
    session_id: str,
    run_id: str,
    external_id: str,
    schema_id: str,
    failure: ContinuationFailure,
) -> ContinuationRecord
```

Commit a validated payload-free provider failure category.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `run_id` | `str` | Required |
> | `external_id` | `str` | Required |
> | `schema_id` | `str` | Required |
> | `failure` | `ContinuationFailure` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> record = await provider.fail(
>     user_id=...,
>     session_id=...,
>     run_id=...,
>     external_id=...,
>     schema_id=...,
>     failure=...,
> )
> ```

### ContinuationProvider.claim

```python theme={null}
async ContinuationProvider.claim(
    *,
    user_id: str,
    session_id: str,
    run_id: str,
    continuation_id: str,
    expected_revision: int,
) -> ContinuationRecord
```

Claim a completed outcome once and return its private value.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `run_id` | `str` | Required |
> | `continuation_id` | `str` | Required |
> | `expected_revision` | `int` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> record = await provider.claim(
>     user_id=...,
>     session_id=...,
>     run_id=...,
>     continuation_id=...,
>     expected_revision=...,
> )
> ```

### ContinuationProvider.arm

```python theme={null}
async ContinuationProvider.arm(record: ContinuationRecord) -> ContinuationRecord
```

Mark a wait resumable only after its framework checkpoint is durable.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `ContinuationRecord` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> record = await provider.arm(record=...)
> ```

### ContinuationProvider.cancel

```python theme={null}
async ContinuationProvider.cancel(record: ContinuationRecord, failure: ContinuationFailure) -> ContinuationRecord
```

Cancel one exact provider wait without dispatching a framework resume.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `ContinuationRecord` | Required |
> | `failure` | `ContinuationFailure` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationProvider
>
> provider: ContinuationProvider
> record = await provider.cancel(record=..., failure=...)
> ```

## ContinuationRecord

Private durable state for one externally completed agent wait.

```python theme={null}
ContinuationRecord(
    continuation_id: str,
    application_id: str,
    user_id: str,
    session_id: str,
    run_id: str,
    provider: str,
    capability: str,
    schema_id: str,
    resume: ResumeArtifact | None = None,
    principal_grants: PrincipalGrantSnapshot | None = None,
    status: ContinuationStatus = 'pending',
    ready: bool = False,
    revision: int = 0,
    result: Any = None,
    failure: ContinuationFailure | None = None,
    created_at: str = ...,
    updated_at: str = ...,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `continuation_id` | `str` | `—` |
| `application_id` | `str` | `—` |
| `user_id` | `str` | `—` |
| `session_id` | `str` | `—` |
| `run_id` | `str` | `—` |
| `provider` | `str` | `—` |
| `capability` | `str` | `—` |
| `schema_id` | `str` | `—` |
| `resume` | `ResumeArtifact \| None` | `None` |
| `principal_grants` | `PrincipalGrantSnapshot \| None` | `None` |
| `status` | `ContinuationStatus` | `'pending'` |
| `ready` | `bool` | `False` |
| `revision` | `int` | `0` |
| `result` | `Any` | `None` |
| `failure` | `ContinuationFailure \| None` | `None` |
| `created_at` | `str` | `<lambda>()` |
| `updated_at` | `str` | `<lambda>()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `continuation_id` | `str` | Required |
> | `application_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `run_id` | `str` | Required |
> | `provider` | `str` | Required |
> | `capability` | `str` | Required |
> | `schema_id` | `str` | Required |
> | `resume` | `ResumeArtifact \| None` | `None` |
> | `principal_grants` | `PrincipalGrantSnapshot \| None` | `None` |
> | `status` | `ContinuationStatus` | `'pending'` |
> | `ready` | `bool` | `False` |
> | `revision` | `int` | `0` |
> | `result` | `Any` | `None` |
> | `failure` | `ContinuationFailure \| None` | `None` |
> | `created_at` | `str` | `...` |
> | `updated_at` | `str` | `...` |
>
> ```python theme={null}
> from harnest.continuation import ContinuationRecord
>
> record = ContinuationRecord(
>     continuation_id=...,
>     application_id=...,
>     user_id=...,
>     session_id=...,
>     run_id=...,
>     provider=...,
>     capability=...,
>     schema_id=...,
> )
> ```

### ContinuationRecord.scope

Return the complete run ownership boundary for this wait.

> [accordion] Example
>
> ```python theme={null}
> from harnest.continuation import ContinuationRecord
>
> record: ContinuationRecord
> value = record.scope
> ```

### ContinuationRecord.pending\_action

Expose only the opaque action needed by the portable run state.

> [accordion] Example
>
> ```python theme={null}
> from harnest.continuation import ContinuationRecord
>
> record: ContinuationRecord
> value = record.pending_action
> ```

## ContinuationStatus

```python theme={null}
ContinuationStatus = Literal['pending', 'completed', 'failed', 'claimed']
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.continuation import ContinuationStatus
> ```

## ContinuationStore

Atomic persistence required by the host-bound provider facade.

```python theme={null}
ContinuationStore(*args, **kwargs)
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> class MyContinuationStore(ContinuationStore):
>     ...
> ```

### ContinuationStore.suspend\_continuation

```python theme={null}
async ContinuationStore.suspend_continuation(*, record: ContinuationRecord, external_id: str) -> ContinuationRecord
```

Persist a new provider wait and atomically suspend its run.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `ContinuationRecord` | Required |
> | `external_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> store: ContinuationStore
> record = await store.suspend_continuation(record=..., external_id=...)
> ```

### ContinuationStore.get\_continuation

```python theme={null}
async ContinuationStore.get_continuation(*, scope: RunScope, continuation_id: str) -> ContinuationRecord | None
```

Read a continuation through its complete run ownership scope.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `continuation_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> store: ContinuationStore
> record = await store.get_continuation(scope=..., continuation_id=...)
> ```

### ContinuationStore.get\_continuation\_by\_external\_id

```python theme={null}
async ContinuationStore.get_continuation_by_external_id(
    *,
    application_id: str,
    provider: str,
    external_id: str,
) -> ProviderPendingContinuation | None
```

Resolve one provider-owned external identifier.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `provider` | `str` | Required |
> | `external_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> store: ContinuationStore
> continuation = await store.get_continuation_by_external_id(
>     application_id=...,
>     provider=...,
>     external_id=...,
> )
> ```

### ContinuationStore.get\_provider\_continuation

```python theme={null}
async ContinuationStore.get_provider_continuation(*, scope: RunScope, provider: str, continuation_id: str) -> ProviderPendingContinuation | None
```

Read one continuation together with its provider-private identity.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `continuation_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> store: ContinuationStore
> continuation = await store.get_provider_continuation(
>     scope=...,
>     provider=...,
>     continuation_id=...,
> )
> ```

### ContinuationStore.list\_pending\_continuations

```python theme={null}
async ContinuationStore.list_pending_continuations(
    *,
    application_id: str,
    provider: str,
    after: str | None = None,
    limit: int = 100,
) -> Sequence[ProviderPendingContinuation]
```

Return a bounded page of waits awaiting provider reconciliation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `application_id` | `str` | Required |
> | `provider` | `str` | Required |
> | `after` | `str \| None` | `None` |
> | `limit` | `int` | `100` |
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> store: ContinuationStore
> result = await store.list_pending_continuations(application_id=..., provider=...)
> ```

### ContinuationStore.resolve\_continuation

```python theme={null}
async ContinuationStore.resolve_continuation(
    *,
    scope: RunScope,
    provider: str,
    external_id: str,
    schema_id: str,
    result: Any = None,
    failure: ContinuationFailure | None = None,
) -> ContinuationRecord
```

Commit a validated provider result or failure for a pending wait.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `external_id` | `str` | Required |
> | `schema_id` | `str` | Required |
> | `result` | `Any` | `None` |
> | `failure` | `ContinuationFailure \| None` | `None` |
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> store: ContinuationStore
> record = await store.resolve_continuation(
>     scope=...,
>     provider=...,
>     external_id=...,
>     schema_id=...,
> )
> ```

### ContinuationStore.claim\_continuation

```python theme={null}
async ContinuationStore.claim_continuation(
    *,
    scope: RunScope,
    provider: str,
    continuation_id: str,
    expected_revision: int,
) -> ContinuationRecord
```

Claim a pending wait using its expected revision.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `continuation_id` | `str` | Required |
> | `expected_revision` | `int` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> store: ContinuationStore
> record = await store.claim_continuation(
>     scope=...,
>     provider=...,
>     continuation_id=...,
>     expected_revision=...,
> )
> ```

### ContinuationStore.arm\_continuation

```python theme={null}
async ContinuationStore.arm_continuation(
    *,
    scope: RunScope,
    provider: str,
    continuation_id: str,
    expected_revision: int,
) -> ContinuationRecord
```

Mark a resolved wait ready to resume using revision-based CAS.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `continuation_id` | `str` | Required |
> | `expected_revision` | `int` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> store: ContinuationStore
> record = await store.arm_continuation(
>     scope=...,
>     provider=...,
>     continuation_id=...,
>     expected_revision=...,
> )
> ```

### ContinuationStore.cancel\_continuation

```python theme={null}
async ContinuationStore.cancel_continuation(
    *,
    scope: RunScope,
    provider: str,
    continuation_id: str,
    expected_revision: int,
    failure: ContinuationFailure,
) -> ContinuationRecord
```

Cancel a wait with a durable failure using revision-based CAS.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `scope` | `RunScope` | Required |
> | `provider` | `str` | Required |
> | `continuation_id` | `str` | Required |
> | `expected_revision` | `int` | Required |
> | `failure` | `ContinuationFailure` | Required |
>
> ```python theme={null}
> from harnest.continuation import ContinuationStore
>
> store: ContinuationStore
> record = await store.cancel_continuation(
>     scope=...,
>     provider=...,
>     continuation_id=...,
>     expected_revision=...,
>     failure=...,
> )
> ```

## ContinuationValidationError

Raised before untrusted external output crosses the durable boundary.

> [accordion] Example
>
> ```python theme={null}
> from harnest.continuation import ContinuationValidationError
>
> try:
>     ...
> except ContinuationValidationError as error:
>     ...
> ```

## ProviderPendingContinuation

A provider-private reconciliation item including its external identity.

```python theme={null}
ProviderPendingContinuation(record: ContinuationRecord, external_id: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `record` | `ContinuationRecord` | `—` |
| `external_id` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `record` | `ContinuationRecord` | Required |
> | `external_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import ProviderPendingContinuation
>
> continuation = ProviderPendingContinuation(record=..., external_id=...)
> ```

## audit\_continuation

Emit mutation outcome without continuation, tenant, or provider payloads.

```python theme={null}
audit_continuation(operation: str, outcome: Literal['committed', 'failed'], backend: str) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `operation` | `str` | Required |
> | `outcome` | `Literal['committed', 'failed']` | Required |
> | `backend` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import audit_continuation
>
> audit_continuation(operation=..., outcome=..., backend=...)
> ```

## continuation\_schema\_id

Fingerprint a JSON schema without persisting its Python source type.

```python theme={null}
continuation_schema_id(schema: Mapping[str, Any]) -> str
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `schema` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.continuation import continuation_schema_id
>
> result = continuation_schema_id(schema=...)
> ```

## external\_id\_key

Build an indexed opaque key while keeping external ids out of indexes.

```python theme={null}
external_id_key(provider: str, external_id: str) -> str
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `provider` | `str` | Required |
> | `external_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.continuation import external_id_key
>
> result = external_id_key(provider=..., external_id=...)
> ```


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