Install the extension
From the agent folder:0.2.2 requires Harnest >=1.0.0,<2 and hatchet-sdk>=1.38,<2.
Submit and await a workflow
Author a domain-specific asynchronous Agent Tool and call the compiler-owned extension namespace:hatchet.status(job) reads the current state. hatchet.cancel(job) requests provider cancellation. Hatchet workers and workflow definitions remain independently deployed; stopping Harnest does not stop them.
Choose an operation
Use
run_and_wait whenever the Tool requires the result. It prevents a known continuation incompatibility from orphaning a newly submitted run. run remains appropriate for intentional fire-and-forget work, and run followed by wait supports an already-owned run.
Configure credentials
The extension declarescontext.credentials and context.continuations. Resolve invocation credentials with only the operations a tool needs:
The deployment must also provide
HATCHET_CLIENT_TOKEN so startup recovery can inspect pending waits after a restart. Keep provider tokens in the credential resolver or process environment, not source, workflow input, continuation results, or logs. The extension disables the SDK’s implicit working-directory dotenv discovery.
Recovery and limits
wait stores an opaque continuation and can resume after process or replica replacement. Recovery retains pending waits across transient Hatchet outages, applies polling backoff, and uses at most 16 concurrent provider clients. Cancellation is a provider request and does not imply immediate worker shutdown.
Agent Runtime Principals can cross an external continuation. Harnest stores only a private versioned snapshot of permission names and reconstructs a fresh opaque principal when another replica resumes the wait. It does not persist principal IDs, credentials, or authentication claims.
Use run_and_wait when the tool needs the result because it verifies durable continuation support before submission. Separate run and wait calls remain available for fire-and-forget and existing-run workflows, but the caller owns the submitted job if a later wait fails for another reason.
Inputs and workflow results must be JSON mappings. The extension rejects either payload above 1 MiB before submission or durable persistence. Job data crosses the external Hatchet boundary, so send only the fields that workflow requires.
The extension does not deploy Hatchet, define workflows, manage workers, expose automatic model tools, or replace Harnest session and checkpoint storage. See Durable execution for continuation behavior and Authentication and credentials for scoped credential providers.
Public API and failure behavior
Every invocation operation resolves only its required credential immediately before constructing the SDK client. Startup recovery instead uses the application service credential. Harnest supplies deterministic idempotency keys for native durable calls and adopts Hatchet’s existing run after an idempotency collision. Provider errors are converted to stable failures without retaining raw exception messages, which may contain credentials. Cancelled and failed terminal jobs resume their Harnest continuation with stable error codes rather than provider payloads.
Workflow names and provider identities must be non-empty. Inputs and results must be finite, acyclic JSON mappings with string keys and encoded size no greater than 1 MiB. Startup recovery uses bounded pages, at most 16 concurrent clients, and exponential polling or outage backoff.