# How TinyAgents Powers OpenHuman's Agent Harness: Checkpoints, Sub-Agents, and Replay

> Discover how TinyAgents empowers OpenHuman's agent harness with checkpoints, durable sub-agents, and automatic replay for robust AI execution. Explore the tinyhumansai openhuman repo.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: deep-dive
- Published: 2026-08-28

---

**OpenHuman's Rust-based agent harness leverages the TinyAgents orchestration framework to execute chat turns through a checkpoint-enabled runtime that supports durable sub-agents, automatic replay journals, and graceful cancellation.**

The `tinyhumansai/openhuman` repository implements a sophisticated adapter layer in `src/openhuman/agent/tinyagents/` that bridges OpenHuman's native types—providers, tools, and messages—with the TinyAgents model-tool-harness API. This integration transforms TinyAgents into the core turn engine while adding OpenHuman-specific capabilities like policy enforcement, per-thread checkpointing, and full replayability.

## TinyAgents as the Turn Execution Engine

Every chat turn in OpenHuman flows through `run_turn_via_tinyagents_shared`, the primary entry point defined in [`src/openhuman/agent/tinyagents/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/tinyagents/mod.rs). This function constructs a `tinyagents::harness::runtime::AgentHarness` and invokes `AgentHarness::invoke` to drive the conversation forward.

The harness operates under a custom `RunPolicy` assembled by `run_policy_for` that enforces OpenHuman's operational limits:

- **Maximum model calls** per turn
- **Maximum tool calls** per turn  
- **Recursion depth** limits for sub-agents
- **Wall-clock timeout** (`DEFAULT_AGENT_TURN_TIMEOUT_SECS` = 10 minutes)

These constraints ensure that long-running agent operations remain within predictable resource boundaries while still allowing complex multi-step reasoning.

## Checkpoint-Enabled Sub-Agents and Delegation

OpenHuman implements durable sub-agent graphs through the delegation subsystem in [`src/openhuman/agent/tinyagents/delegation.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/tinyagents/delegation.rs). This module enables **checkpoint-enabled delegations** that can pause execution—for example, when awaiting user approval—and resume later without losing state.

The checkpointing mechanism relies on `tinyagents::graph::checkpoint::FileCheckpointer`, which persists state per-thread using a unique `thread_id`:

```rust
use openhuman::agent::tinyagents::delegation::{DelegationConfig, run_or_resume_delegation};
use tinyagents::graph::checkpoint::FileCheckpointer;
use std::sync::Arc;

// Initialize a file-based checkpointer for this workspace
let checkpointer = FileCheckpointer::new("/workspace/tinyagents_store");

let config = DelegationConfig {
    thread_id: "thread-abc-123".into(),
    checkpointer: Some(Arc::new(checkpointer)),
    ..Default::default()
};

// Execute or resume the delegation graph
let result = run_or_resume_delegation(config, agent_graph).await?;

```

When a sub-agent pauses, the harness writes a checkpoint via `graph.with_checkpointer(cp)`. The `run_or_resume_delegation` function (lines 302-356 in [`delegation.rs`](https://github.com/tinyhumansai/openhuman/blob/main/delegation.rs)) handles the logic: it checks for existing checkpoints, validates schema version compatibility, and either resumes from the saved state or starts fresh. Stale checkpoints are automatically pruned, ensuring forward and backward compatibility across schema versions.

## Replay and Journal Persistence

All turn events—including model streaming tokens, tool call invocations, and sub-agent progress—are durably recorded through two parallel mechanisms:

1. **UI Progress Bridge**: The `OpenhumanEventBridge` (defined in [`observability.rs`](https://github.com/tinyhumansai/openhuman/blob/main/observability.rs), referenced in [`mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/mod.rs) lines 14-16) streams real-time events to OpenHuman's `AgentProgress` UI components.

2. **Durable Journal**: The `tinyagents::harness::journal` API persists a complete ledger of the turn execution. The [`src/openhuman/agent/tinyagents/replay.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/tinyagents/replay.rs) module provides utilities to retrieve this history:

```rust
use openhuman::agent::tinyagents::journal::{read_run_events, take_request_journal_run};

// Retrieve all events for a specific run
let events = read_run_events("run-uuid-456").await?;
for event in events {
    println!("{}: {}", event.timestamp, event.description);
}

// Fetch the complete run record for debugging
let run = take_request_journal_run("run-uuid-456").await?;

```

These journal functions enable developers to replay past turns, audit sub-agent behavior, and debug complex delegation chains by inspecting the exact sequence of model responses and tool invocations.

## Tool Integration and Policy Enforcement

OpenHuman's native tools integrate with TinyAgents through the `SharedToolAdapter` in [`src/openhuman/agent/tinyagents/tools.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/tinyagents/tools.rs). This adapter implements the TinyAgents `Tool` trait while forwarding execution to OpenHuman's underlying tool implementations.

Policy enforcement occurs via `ToolPolicyMiddleware` (referenced in [`mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/mod.rs) lines 7-10), which intercepts tool calls before execution to enforce:

- Rate limits
- Deny-lists
- Per-channel usage caps
- Session-specific restrictions

Each tool execution is automatically recorded in the journal, creating an immutable audit trail of what actions the agent attempted and what policies were applied.

## Thread Context, Cancellation, and Observability

### Thread-Local Context

The [`src/openhuman/agent/tinyagents/thread_context.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/tinyagents/thread_context.rs) module binds graph execution to conversation-specific workspaces. Helper functions like `current_thread_id` and `with_thread_id` ensure that checkpoints and key-value state are isolated per thread, typically stored under `tinyagents_store/kv/{thread_id}/`.

### Graceful Cancellation

Cancellation signals propagate through the entire delegation graph using `tinyagents::harness::stop_hooks`. The [`stop_hooks.rs`](https://github.com/tinyhumansai/openhuman/blob/main/stop_hooks.rs) middleware (lines 22-23 in [`mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/mod.rs)) watches for abort signals and converts them into `AbortGuard` instances. Combined with [`run_cancellation_context.rs`](https://github.com/tinyhumansai/openhuman/blob/main/run_cancellation_context.rs) (lines 8-10), which supplies a `CancellationToken`, this ensures that user-initiated stops gracefully terminate all in-flight tool calls and sub-agent operations.

### Observability

The [`observability.rs`](https://github.com/tinyhumansai/openhuman/blob/main/observability.rs) module hooks into TinyAgents events to generate cost footers, summarize checkpoint states, and determine when to surface checkpoint events as user-visible messages in the UI.

## Summary

- **Turn Execution**: OpenHuman uses `run_turn_via_tinyagents_shared` in [`mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/mod.rs) to orchestrate chat turns through TinyAgents' `AgentHarness`, enforcing timeouts and call limits via `RunPolicy`.
- **Checkpointing**: The [`delegation.rs`](https://github.com/tinyhumansai/openhuman/blob/main/delegation.rs) module implements durable sub-agents using `FileCheckpointer` and `run_or_resume_delegation`, enabling pause-and-resume workflows with schema version handling.
- **Replay Capability**: Journal utilities in [`replay.rs`](https://github.com/tinyhumansai/openhuman/blob/main/replay.rs) provide `read_run_events` and `take_request_journal_run` for debugging and auditing agent behavior.
- **Tool Integration**: `SharedToolAdapter` bridges OpenHuman tools to TinyAgents, while `ToolPolicyMiddleware` enforces rate limits and security policies before execution.
- **Lifecycle Management**: Thread context isolation, cancellation tokens, and observability hooks ensure robust, observable agent operations across complex delegation graphs.

## Frequently Asked Questions

### What is TinyAgents' role in the OpenHuman architecture?

TinyAgents serves as the core orchestration engine that executes OpenHuman's agent turns. Rather than implementing a custom runtime, OpenHuman adapts its native types—chat models, tools, and messages—into the TinyAgents API through the adapter layer in `src/openhuman/agent/tinyagents/`. This allows OpenHuman to leverage TinyAgents' proven graph execution, checkpointing, and journaling capabilities while maintaining its own provider abstractions and UI integration.

### How does checkpointing enable durable sub-agents?

When a sub-agent (delegation) needs to pause—such as when awaiting user approval or an external webhook—the system writes a checkpoint using `FileCheckpointer` configured with the current `thread_id`. The `run_or_resume_delegation` function checks for these saved states on startup; if found and valid, it resumes execution from the exact point of interruption. If the checkpoint schema is outdated or corrupted, the system prunes it and starts fresh, ensuring robustness across software updates.

### Can agent turns be replayed after completion for debugging?

Yes. Every turn writes to the TinyAgents journal, which records the complete sequence of model calls, tool executions, and checkpoints. Developers can use `read_run_events` to inspect the event stream or `take_request_journal_run` to retrieve the full execution context. This journal persists independently of the UI, allowing for post-hoc analysis of complex multi-step agent behaviors or sub-agent delegation chains.

### How does OpenHuman handle cancellation of long-running agent operations?

Cancellation flows through two coordinated mechanisms: the [`stop_hooks.rs`](https://github.com/tinyhumansai/openhuman/blob/main/stop_hooks.rs) middleware registers an `AbortGuard` that monitors for shutdown signals, while [`run_cancellation_context.rs`](https://github.com/tinyhumansai/openhuman/blob/main/run_cancellation_context.rs) provides a `CancellationToken` that propagates through the entire delegation graph. When a user aborts a turn, this token ensures that all in-flight tool calls receive termination signals and the checkpoint is left in a consistent state for potential future resumption.