harnest.continuation

All Python modules · Import and compatibility guidance

Exports

Name	Kind
`ContinuationConflictError`	Class
`ContinuationError`	Class
`ContinuationFailure`	Class
`ContinuationProvider`	Class
`ContinuationRecord`	Class
`ContinuationStatus`	Value or type alias
`ContinuationStore`	Class
`ContinuationValidationError`	Class
`ProviderPendingContinuation`	Class
`audit_continuation`	Function
`continuation_schema_id`	Function
`external_id_key`	Function

ContinuationConflictError

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

Example

from harnest.continuation import ContinuationConflictError

try:
    ...
except ContinuationConflictError as error:
    ...

ContinuationError

Base error for external continuation ownership and persistence.

Example

from harnest.continuation import ContinuationError

try:
    ...
except ContinuationError as error:
    ...

ContinuationFailure

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

ContinuationFailure(code: str, retryable: bool = False) -> None

Fields (— means no declared default):

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

Parameters and example

Parameter	Type	Default
`code`	`str`	Required
`retryable`	`bool`	`False`

from harnest.continuation import ContinuationFailure

failure = ContinuationFailure(code=...)

ContinuationProvider

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

ContinuationProvider(store: ContinuationStore, *, application_id: str, provider: str) -> None

Parameters and example

Parameter	Type	Default
`store`	`ContinuationStore`	Required
`application_id`	`str`	Required
`provider`	`str`	Required

from harnest.continuation import ContinuationProvider

provider = ContinuationProvider(store=..., application_id=..., provider=...)

ContinuationProvider.name

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

Example

from harnest.continuation import ContinuationProvider

provider: ContinuationProvider
value = provider.name

ContinuationProvider.suspend

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.

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`

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

async ContinuationProvider.lookup(external_id: str) -> ProviderPendingContinuation | None

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

Parameters and example

Parameter	Type	Default
`external_id`	`str`	Required

from harnest.continuation import ContinuationProvider

provider: ContinuationProvider
continuation = await provider.lookup(external_id=...)

ContinuationProvider.get

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.

Parameters and example

Parameter	Type	Default
`user_id`	`str`	Required
`session_id`	`str`	Required
`run_id`	`str`	Required
`continuation_id`	`str`	Required

from harnest.continuation import ContinuationProvider

provider: ContinuationProvider
record = await provider.get(
    user_id=...,
    session_id=...,
    run_id=...,
    continuation_id=...,
)

ContinuationProvider.get_pending

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.

Parameters and example

Parameter	Type	Default
`user_id`	`str`	Required
`session_id`	`str`	Required
`run_id`	`str`	Required
`continuation_id`	`str`	Required

from harnest.continuation import ContinuationProvider

provider: ContinuationProvider
continuation = await provider.get_pending(
    user_id=...,
    session_id=...,
    run_id=...,
    continuation_id=...,
)

ContinuationProvider.list_pending

async ContinuationProvider.list_pending(*, after: str | None = None, limit: int = 100) -> Sequence[ProviderPendingContinuation]

Read one bounded indexed page for provider startup reconciliation.

Parameters and example

Parameter	Type	Default
`after`	`str \| None`	`None`
`limit`	`int`	`100`

from harnest.continuation import ContinuationProvider

provider: ContinuationProvider
result = await provider.list_pending()

ContinuationProvider.complete

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.

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

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

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.

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

from harnest.continuation import ContinuationProvider

provider: ContinuationProvider
record = await provider.fail(
    user_id=...,
    session_id=...,
    run_id=...,
    external_id=...,
    schema_id=...,
    failure=...,
)

ContinuationProvider.claim

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.

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

from harnest.continuation import ContinuationProvider

provider: ContinuationProvider
record = await provider.claim(
    user_id=...,
    session_id=...,
    run_id=...,
    continuation_id=...,
    expected_revision=...,
)

ContinuationProvider.arm

async ContinuationProvider.arm(record: ContinuationRecord) -> ContinuationRecord

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

Parameters and example

Parameter	Type	Default
`record`	`ContinuationRecord`	Required

from harnest.continuation import ContinuationProvider

provider: ContinuationProvider
record = await provider.arm(record=...)

ContinuationProvider.cancel

async ContinuationProvider.cancel(record: ContinuationRecord, failure: ContinuationFailure) -> ContinuationRecord

Cancel one exact provider wait without dispatching a framework resume.

Parameters and example

Parameter	Type	Default
`record`	`ContinuationRecord`	Required
`failure`	`ContinuationFailure`	Required

from harnest.continuation import ContinuationProvider

provider: ContinuationProvider
record = await provider.cancel(record=..., failure=...)

ContinuationRecord

Private durable state for one externally completed agent wait.

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

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`	`...`

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.

Example

from harnest.continuation import ContinuationRecord

record: ContinuationRecord
value = record.scope

ContinuationRecord.pending_action

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

Example

from harnest.continuation import ContinuationRecord

record: ContinuationRecord
value = record.pending_action

ContinuationStatus

ContinuationStatus = Literal['pending', 'completed', 'failed', 'claimed']

Example

from harnest.continuation import ContinuationStatus

ContinuationStore

Atomic persistence required by the host-bound provider facade.

ContinuationStore(*args, **kwargs)

Example

from harnest.continuation import ContinuationStore

class MyContinuationStore(ContinuationStore):
    ...

ContinuationStore.suspend_continuation

async ContinuationStore.suspend_continuation(*, record: ContinuationRecord, external_id: str) -> ContinuationRecord

Persist a new provider wait and atomically suspend its run.

Parameters and example

Parameter	Type	Default
`record`	`ContinuationRecord`	Required
`external_id`	`str`	Required

from harnest.continuation import ContinuationStore

store: ContinuationStore
record = await store.suspend_continuation(record=..., external_id=...)

ContinuationStore.get_continuation

async ContinuationStore.get_continuation(*, scope: RunScope, continuation_id: str) -> ContinuationRecord | None

Read a continuation through its complete run ownership scope.

Parameters and example

Parameter	Type	Default
`scope`	`RunScope`	Required
`continuation_id`	`str`	Required

from harnest.continuation import ContinuationStore

store: ContinuationStore
record = await store.get_continuation(scope=..., continuation_id=...)

ContinuationStore.get_continuation_by_external_id

async ContinuationStore.get_continuation_by_external_id(
    *,
    application_id: str,
    provider: str,
    external_id: str,
) -> ProviderPendingContinuation | None

Resolve one provider-owned external identifier.

Parameters and example

Parameter	Type	Default
`application_id`	`str`	Required
`provider`	`str`	Required
`external_id`	`str`	Required

from harnest.continuation import ContinuationStore

store: ContinuationStore
continuation = await store.get_continuation_by_external_id(
    application_id=...,
    provider=...,
    external_id=...,
)

ContinuationStore.get_provider_continuation

async ContinuationStore.get_provider_continuation(*, scope: RunScope, provider: str, continuation_id: str) -> ProviderPendingContinuation | None

Read one continuation together with its provider-private identity.

Parameters and example

Parameter	Type	Default
`scope`	`RunScope`	Required
`provider`	`str`	Required
`continuation_id`	`str`	Required

from harnest.continuation import ContinuationStore

store: ContinuationStore
continuation = await store.get_provider_continuation(
    scope=...,
    provider=...,
    continuation_id=...,
)

ContinuationStore.list_pending_continuations

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.

Parameters and example

Parameter	Type	Default
`application_id`	`str`	Required
`provider`	`str`	Required
`after`	`str \| None`	`None`
`limit`	`int`	`100`

from harnest.continuation import ContinuationStore

store: ContinuationStore
result = await store.list_pending_continuations(application_id=..., provider=...)

ContinuationStore.resolve_continuation

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.

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`

from harnest.continuation import ContinuationStore

store: ContinuationStore
record = await store.resolve_continuation(
    scope=...,
    provider=...,
    external_id=...,
    schema_id=...,
)

ContinuationStore.claim_continuation

async ContinuationStore.claim_continuation(
    *,
    scope: RunScope,
    provider: str,
    continuation_id: str,
    expected_revision: int,
) -> ContinuationRecord

Claim a pending wait using its expected revision.

Parameters and example

Parameter	Type	Default
`scope`	`RunScope`	Required
`provider`	`str`	Required
`continuation_id`	`str`	Required
`expected_revision`	`int`	Required

from harnest.continuation import ContinuationStore

store: ContinuationStore
record = await store.claim_continuation(
    scope=...,
    provider=...,
    continuation_id=...,
    expected_revision=...,
)

ContinuationStore.arm_continuation

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.

Parameters and example

Parameter	Type	Default
`scope`	`RunScope`	Required
`provider`	`str`	Required
`continuation_id`	`str`	Required
`expected_revision`	`int`	Required

from harnest.continuation import ContinuationStore

store: ContinuationStore
record = await store.arm_continuation(
    scope=...,
    provider=...,
    continuation_id=...,
    expected_revision=...,
)

ContinuationStore.cancel_continuation

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.

Parameters and example

Parameter	Type	Default
`scope`	`RunScope`	Required
`provider`	`str`	Required
`continuation_id`	`str`	Required
`expected_revision`	`int`	Required
`failure`	`ContinuationFailure`	Required

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.

Example

from harnest.continuation import ContinuationValidationError

try:
    ...
except ContinuationValidationError as error:
    ...

ProviderPendingContinuation

A provider-private reconciliation item including its external identity.

ProviderPendingContinuation(record: ContinuationRecord, external_id: str) -> None

Fields (— means no declared default):

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

Parameters and example

Parameter	Type	Default
`record`	`ContinuationRecord`	Required
`external_id`	`str`	Required

from harnest.continuation import ProviderPendingContinuation

continuation = ProviderPendingContinuation(record=..., external_id=...)

audit_continuation

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

audit_continuation(operation: str, outcome: Literal['committed', 'failed'], backend: str) -> None

Parameters and example

Parameter	Type	Default
`operation`	`str`	Required
`outcome`	`Literal['committed', 'failed']`	Required
`backend`	`str`	Required

from harnest.continuation import audit_continuation

audit_continuation(operation=..., outcome=..., backend=...)

continuation_schema_id

Fingerprint a JSON schema without persisting its Python source type.

continuation_schema_id(schema: Mapping[str, Any]) -> str

Parameters and example

Parameter	Type	Default
`schema`	`Mapping[str, Any]`	Required

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.

external_id_key(provider: str, external_id: str) -> str

Parameters and example

Parameter	Type	Default
`provider`	`str`	Required
`external_id`	`str`	Required

from harnest.continuation import external_id_key

result = external_id_key(provider=..., external_id=...)

​Exports

​ContinuationConflictError

​ContinuationError

​ContinuationFailure

​ContinuationProvider

​ContinuationProvider.name

​ContinuationProvider.suspend

​ContinuationProvider.lookup

​ContinuationProvider.get

​ContinuationProvider.get_pending

​ContinuationProvider.list_pending

​ContinuationProvider.complete

​ContinuationProvider.fail

​ContinuationProvider.claim

​ContinuationProvider.arm

​ContinuationProvider.cancel

​ContinuationRecord

​ContinuationRecord.scope

​ContinuationRecord.pending_action

​ContinuationStatus

​ContinuationStore

​ContinuationStore.suspend_continuation

​ContinuationStore.get_continuation

​ContinuationStore.get_continuation_by_external_id

​ContinuationStore.get_provider_continuation

​ContinuationStore.list_pending_continuations

​ContinuationStore.resolve_continuation

​ContinuationStore.claim_continuation

​ContinuationStore.arm_continuation

​ContinuationStore.cancel_continuation

​ContinuationValidationError

​ProviderPendingContinuation

​audit_continuation

​continuation_schema_id

​external_id_key

Exports

ContinuationConflictError

ContinuationError

ContinuationFailure

ContinuationProvider

ContinuationProvider.name

ContinuationProvider.suspend

ContinuationProvider.lookup

ContinuationProvider.get

ContinuationProvider.get_pending

ContinuationProvider.list_pending

ContinuationProvider.complete

ContinuationProvider.fail

ContinuationProvider.claim

ContinuationProvider.arm

ContinuationProvider.cancel

ContinuationRecord

ContinuationRecord.scope

ContinuationRecord.pending_action

ContinuationStatus

ContinuationStore

ContinuationStore.suspend_continuation

ContinuationStore.get_continuation

ContinuationStore.get_continuation_by_external_id

ContinuationStore.get_provider_continuation

ContinuationStore.list_pending_continuations

ContinuationStore.resolve_continuation

ContinuationStore.claim_continuation

ContinuationStore.arm_continuation

ContinuationStore.cancel_continuation

ContinuationValidationError

ProviderPendingContinuation

audit_continuation

continuation_schema_id

external_id_key