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

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

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) 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, referenced in 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 module provides utilities to retrieve this history:

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. 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 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 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 middleware (lines 22-23 in mod.rs) watches for abort signals and converts them into AbortGuard instances. Combined with 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 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 to orchestrate chat turns through TinyAgents' AgentHarness, enforcing timeouts and call limits via RunPolicy.
• Checkpointing: The 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 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 middleware registers an AbortGuard that monitors for shutdown signals, while 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}