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

# Upgrade from 4.8.3 to 4.9.0

> Adopt 4.9 execution graphs and dependability changes, adapt custom harness services, and preserve persistent storage and checkpoint compatibility.

This guide covers **Agentium 4.9.0** against the 4.8.3 baseline. Follow [installation](/learn/installation) to install the published packages, and keep all ten Agentium packages on matching versions. Read [release and upgrade guidance](/reference/releases) before changing custom harness services or persistent storage.

## Adapt custom harness services and wrappers

Normal runtime-provided services already implement the new contract. Handwritten `HarnessExecutionServices` implementations and test doubles must provide required `observeToolSettlements`, `budget`, `archivedHistory`, `retrieveHistory` and `finishModel` members. Custom `RunHandle` wrappers must also provide `budget`. Recompile against the [generated runtime contracts](/harness/api/runtime) instead of copying an older interface.

These requirements support complete tool-batch observations, retained resource accounting, bounded history and finishing calls. Forward the runtime members when wrapping a real service. A placeholder that silently drops observations or returns fabricated evidence weakens the advertised contract.

## Use the asynchronous accounting path

After canonical accounting has been used, the synchronous string-argument overload `CostTracker.checkBudget(runId)`, `checkInProgressBudget()`, `isBudgetExceeded()` and `estimateRemaining()` throw even when observed usage is complete. Use the asynchronous `await tracker.checkBudget(accountingScope, bound)` overload and accounting queries from the [cost reference](/api-reference/core/cost); retain `result.costs` for the settled run snapshot. Unknown usage remains unknown, and incomplete amounts stay visible.

## Update lifecycle and outcome handling

Cancel and await admitted Agent work before close. Busy/closing/closed components reject admission. Owned memory/accounting drain waits for settlement, and incomplete teardown can be retried without reopening execution. Inspect acknowledgment/drain diagnostics instead of assuming a fire-and-forget memory write succeeded.

Workflow joins use only produced patches. Ordinary failures retain diagnostics and make aggregate status `failed`; canceled child work propagates cancellation and prevents late patches/checkpoints. Configure `failurePolicy` deliberately and recognize stable reason/error codes. If handling `StepDef` or reasons exhaustively, include graph/repeat variants and `workflow_iteration_limit`.

## Preserve storage identities and checkpoints

Persistent scope wrappers and Redis retain `legacy` key encoding by default. Opt into `tuple-v1` explicitly for a new key space; no fallback scan or automatic migration occurs. Configure both layers when using a scope wrapper over Redis. Stop writers, back up TTLs, verify identity and collisions, then migrate keys offline. Borrowed wrappers require `ownsInner: false` when the host closes a shared driver.

For versioned Workflow continuation, configure `definitionVersion` and `validateCheckpointState` together. Migrate legacy records only after verifying the original absolute cursor, code identity and state. `replay()`/`fork()` remain compatibility wrappers for fresh execution; they are deprecated terminology, and cannot provide recorded playback. See [checkpoint continuation](/workflows/time-travel).

## Adopt new capabilities explicitly

| Need | Guide | Integration limit |
| - | - | - |
| Dependency coordination and bounded repeated episodes | [Workflow graphs](/workflows/graphs) | Completed-boundary checkpoints; local node limits |
| Per-node recovery and one shared dispatch ceiling | [Recoverable execution graphs](/harness/execution-graphs) | Stateless JSON binding contract, host versions, durable CAS and effect evidence |
| Model proposals and streamed pending changes | [Bounded graph planning](/harness/execution-graphs#add-bounded-model-planning) | Complete validated proposals; claimed work immutable; no effect rollback |
| Evidence-backed continuity | [Recall and summaries](/harness/continuity) | Host-owned scope, physical read bounds and current revisions |
| Completion proof | [Current-evidence verification](/harness/continuity#verify-completion-using-current-facts) | `unknown` stops; revision effects need explicit permission |

No public export removals are expected against 4.8.3, but required custom-interface members and stricter lifecycle/outcome handling still require application review. Ordinary Agent, Workflow and HarnessRuntime paths remain available. In-memory stores do not become durable after upgrading; cancellation cannot retract remote work; recovery does not replenish budgets or guarantee exactly-once effects.

## Re-run your application checks

Compile wrappers and exhaustive unions, run deterministic happy/failure cases, and exercise your backend's crash/receipt/reconciliation windows. Local SDK fixtures and package-consumer checks establish the covered contracts. Live-provider quality, carrier/device behavior, distributed failover and production deployment need separate application evidence.


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