> ## 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.extensions.hatchet

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

## Workflow operations

| Operation | Result | Ownership |
| - | - | - |
| `run(name, input)` | `HatchetRun` | Submit and return immediately; the caller owns any later wait |
| `status(job)` | `HatchetRunStatus` | Read `QUEUED`, `RUNNING`, `COMPLETED`, `CANCELLED`, or `FAILED` |
| `wait(job)` | JSON mapping | Persist a continuation and resume when an existing run terminates |
| `run_and_wait(name, input)` | JSON mapping | Prove durable suspension support before submitting and waiting |
| `cancel(job)` | None | Request provider cancellation without claiming worker termination |

## Public contracts

| API | Role |
| - | - |
| `hatchet` / `extension` | Installed `HatchetExtension` singleton |
| `HatchetRun` | Immutable provider run, workflow, and correlation identity |
| `HatchetRunStatus` | Stable provider-neutral terminal and non-terminal status enum |
| `HatchetContext` | Revocable invocation-scoped view used by the extension singleton |

## Exports

| Name | Kind |
| - | - |
| [`HatchetContext`](#hatchetcontext) | Class |
| [`HatchetExtension`](#hatchetextension) | Class |
| [`HatchetRun`](#hatchetrun) | Class |
| [`HatchetRunStatus`](#hatchetrunstatus) | Class |
| [`hatchet`](#hatchet) | Namespace |
| [`extension`](#extension) | Namespace |

## HatchetContext

Typed invocation view exposed through `context.extensions("hatchet")`.

```python theme={null}
HatchetContext(extension_name: str, owner: 'HatchetExtension') -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `extension_name` | `str` | Required |
> | `owner` | `'HatchetExtension'` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetContext
>
> context = HatchetContext(extension_name=..., owner=...)
> ```

### HatchetContext.extension\_name

Return the extension whose invocation authority this context carries.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetContext
>
> context: HatchetContext
> value = context.extension_name
> ```

### HatchetContext.active

Report whether the owning managed invocation is still active.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetContext
>
> context: HatchetContext
> value = context.active
> ```

### HatchetContext.continuations

Return provider-bound suspension authority for this invocation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetContext
>
> context: HatchetContext
> value = context.continuations
> ```

### HatchetContext.run

```python theme={null}
async HatchetContext.run(workflow_name: str, job_input: Mapping[str, Any]) -> HatchetRun
```

Submit external work without waiting in the agent request.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `workflow_name` | `str` | Required |
> | `job_input` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetContext
>
> context: HatchetContext
> run = await context.run(workflow_name=..., job_input=...)
> ```

### HatchetContext.status

```python theme={null}
async HatchetContext.status(job: HatchetRun) -> HatchetRunStatus
```

Read one external job status through invocation credentials.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetContext
>
> context: HatchetContext
> status = await context.status(job=...)
> ```

### HatchetContext.wait

```python theme={null}
async HatchetContext.wait(job: HatchetRun) -> Mapping[str, Any]
```

Suspend this tool continuation until Hatchet reaches a terminal state.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetContext
>
> context: HatchetContext
> result = await context.wait(job=...)
> ```

### HatchetContext.run\_and\_wait

```python theme={null}
async HatchetContext.run_and_wait(workflow_name: str, job_input: Mapping[str, Any]) -> Mapping[str, Any]
```

Preflight durable suspension before submitting external work.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `workflow_name` | `str` | Required |
> | `job_input` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetContext
>
> context: HatchetContext
> result = await context.run_and_wait(workflow_name=..., job_input=...)
> ```

### HatchetContext.cancel

```python theme={null}
async HatchetContext.cancel(job: HatchetRun) -> None
```

Request cancellation while leaving worker shutdown to its owner.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetContext
>
> context: HatchetContext
> await context.cancel(job=...)
> ```

## HatchetExtension

Expose Hatchet as an invocation-safe native extension capability.

```python theme={null}
HatchetExtension() -> None
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension = HatchetExtension()
> ```

### HatchetExtension.start

```python theme={null}
async HatchetExtension.start(start_context: Any) -> None
```

Register validation before restoring pending provider monitors.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `start_context` | `Any` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension: HatchetExtension
> await extension.start(start_context=...)
> ```

### HatchetExtension.stop

```python theme={null}
async HatchetExtension.stop() -> None
```

Stop local pollers without cancelling independently durable Hatchet jobs.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension: HatchetExtension
> await extension.stop()
> ```

### HatchetExtension.create\_context

```python theme={null}
HatchetExtension.create_context(base: ExtensionContext) -> HatchetContext
```

Create a fresh revocable view after extension startup succeeds.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `base` | `ExtensionContext` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension: HatchetExtension
> context = extension.create_context(base=...)
> ```

### HatchetExtension.context

Return the task-local extension context for the active invocation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension: HatchetExtension
> value = extension.context
> ```

### HatchetExtension.run

```python theme={null}
async HatchetExtension.run(workflow_name: str, job_input: Mapping[str, Any]) -> HatchetRun
```

Submit work through the context active in the current invocation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `workflow_name` | `str` | Required |
> | `job_input` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension: HatchetExtension
> run = await extension.run(workflow_name=..., job_input=...)
> ```

### HatchetExtension.status

```python theme={null}
async HatchetExtension.status(job: HatchetRun) -> HatchetRunStatus
```

Read job status through the active typed context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension: HatchetExtension
> status = await extension.status(job=...)
> ```

### HatchetExtension.wait

```python theme={null}
async HatchetExtension.wait(job: HatchetRun) -> Mapping[str, Any]
```

Suspend and resume the active authored tool continuation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension: HatchetExtension
> result = await extension.wait(job=...)
> ```

### HatchetExtension.run\_and\_wait

```python theme={null}
async HatchetExtension.run_and_wait(workflow_name: str, job_input: Mapping[str, Any]) -> Mapping[str, Any]
```

Submit only after the current invocation proves it can suspend.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `workflow_name` | `str` | Required |
> | `job_input` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension: HatchetExtension
> result = await extension.run_and_wait(workflow_name=..., job_input=...)
> ```

### HatchetExtension.cancel

```python theme={null}
async HatchetExtension.cancel(job: HatchetRun) -> None
```

Cancel an external run through the active typed context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetExtension
>
> extension: HatchetExtension
> await extension.cancel(job=...)
> ```

## HatchetRun

Portable identity for work owned by the external Hatchet runtime.

```python theme={null}
HatchetRun(run_id: str, workflow_name: str, correlation_id: str) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `run_id` | `str` | `—` |
| `workflow_name` | `str` | `—` |
| `correlation_id` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `run_id` | `str` | Required |
> | `workflow_name` | `str` | Required |
> | `correlation_id` | `str` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetRun
>
> run = HatchetRun(run_id=..., workflow_name=..., correlation_id=...)
> ```

## HatchetRunStatus

Provider statuses that affect continuation decisions.

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

| Member | Value |
| - | - |
| `QUEUED` | `'QUEUED'` |
| `RUNNING` | `'RUNNING'` |
| `COMPLETED` | `'COMPLETED'` |
| `CANCELLED` | `'CANCELLED'` |
| `FAILED` | `'FAILED'` |

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import HatchetRunStatus
>
> value = HatchetRunStatus.QUEUED
> ```

## hatchet

Expose Hatchet as an invocation-safe native extension capability.

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

### hatchet.start

```python theme={null}
async hatchet.start(start_context: Any) -> None
```

Register validation before restoring pending provider monitors.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `start_context` | `Any` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import hatchet
>
> await hatchet.start(start_context=...)
> ```

### hatchet.stop

```python theme={null}
async hatchet.stop() -> None
```

Stop local pollers without cancelling independently durable Hatchet jobs.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import hatchet
>
> await hatchet.stop()
> ```

### hatchet.create\_context

```python theme={null}
hatchet.create_context(base: ExtensionContext) -> HatchetContext
```

Create a fresh revocable view after extension startup succeeds.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `base` | `ExtensionContext` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import hatchet
>
> context = hatchet.create_context(base=...)
> ```

### hatchet.context

Return the task-local extension context for the active invocation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import hatchet
>
> value = hatchet.context
> ```

### hatchet.run

```python theme={null}
async hatchet.run(workflow_name: str, job_input: Mapping[str, Any]) -> HatchetRun
```

Submit work through the context active in the current invocation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `workflow_name` | `str` | Required |
> | `job_input` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import hatchet
>
> run = await hatchet.run(workflow_name=..., job_input=...)
> ```

### hatchet.status

```python theme={null}
async hatchet.status(job: HatchetRun) -> HatchetRunStatus
```

Read job status through the active typed context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import hatchet
>
> status = await hatchet.status(job=...)
> ```

### hatchet.wait

```python theme={null}
async hatchet.wait(job: HatchetRun) -> Mapping[str, Any]
```

Suspend and resume the active authored tool continuation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import hatchet
>
> result = await hatchet.wait(job=...)
> ```

### hatchet.run\_and\_wait

```python theme={null}
async hatchet.run_and_wait(workflow_name: str, job_input: Mapping[str, Any]) -> Mapping[str, Any]
```

Submit only after the current invocation proves it can suspend.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `workflow_name` | `str` | Required |
> | `job_input` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import hatchet
>
> result = await hatchet.run_and_wait(workflow_name=..., job_input=...)
> ```

### hatchet.cancel

```python theme={null}
async hatchet.cancel(job: HatchetRun) -> None
```

Cancel an external run through the active typed context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import hatchet
>
> await hatchet.cancel(job=...)
> ```

## extension

Expose Hatchet as an invocation-safe native extension capability.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
> ```

### extension.start

```python theme={null}
async extension.start(start_context: Any) -> None
```

Register validation before restoring pending provider monitors.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `start_context` | `Any` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
>
> await extension.start(start_context=...)
> ```

### extension.stop

```python theme={null}
async extension.stop() -> None
```

Stop local pollers without cancelling independently durable Hatchet jobs.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
>
> await extension.stop()
> ```

### extension.create\_context

```python theme={null}
extension.create_context(base: ExtensionContext) -> HatchetContext
```

Create a fresh revocable view after extension startup succeeds.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `base` | `ExtensionContext` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
>
> context = extension.create_context(base=...)
> ```

### extension.context

Return the task-local extension context for the active invocation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
>
> value = extension.context
> ```

### extension.run

```python theme={null}
async extension.run(workflow_name: str, job_input: Mapping[str, Any]) -> HatchetRun
```

Submit work through the context active in the current invocation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `workflow_name` | `str` | Required |
> | `job_input` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
>
> run = await extension.run(workflow_name=..., job_input=...)
> ```

### extension.status

```python theme={null}
async extension.status(job: HatchetRun) -> HatchetRunStatus
```

Read job status through the active typed context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
>
> status = await extension.status(job=...)
> ```

### extension.wait

```python theme={null}
async extension.wait(job: HatchetRun) -> Mapping[str, Any]
```

Suspend and resume the active authored tool continuation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
>
> result = await extension.wait(job=...)
> ```

### extension.run\_and\_wait

```python theme={null}
async extension.run_and_wait(workflow_name: str, job_input: Mapping[str, Any]) -> Mapping[str, Any]
```

Submit only after the current invocation proves it can suspend.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `workflow_name` | `str` | Required |
> | `job_input` | `Mapping[str, Any]` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
>
> result = await extension.run_and_wait(workflow_name=..., job_input=...)
> ```

### extension.cancel

```python theme={null}
async extension.cancel(job: HatchetRun) -> None
```

Cancel an external run through the active typed context.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `job` | `HatchetRun` | Required |
>
> ```python theme={null}
> from harnest.extensions.hatchet import extension
>
> await extension.cancel(job=...)
> ```


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