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

# Agent harness

> Understand the bounded execution loop, budgets, tools, and recovery boundaries.

Formation runs an agent as a bounded loop: assemble permitted context, call a model,
validate and execute tools, then answer. A **run** is the durable record of that
work. It belongs to one agent and one conversation, even when several people
contribute messages while it is running.

## What a run contains

A run records its triggering messages, admitted budget, model calls, tool calls,
observations, progress, and final outcome. A run step groups one reasoning
iteration with the tools it requested. Prompt snapshots record the assembled
context supplied to model calls.

The database permits one active run per agent and conversation. Other
conversations can run concurrently within installation and agent capacity limits.
A new message can update an existing run through [live steering](https://docs.formation.texturehq.com/runtime/live-steering.md)
or wait for a later conversational turn.

## Models and tools

Each agent has primary, fast, and heartbeat model settings. Primary serves
ordinary conversation; fast handles drafting and extraction. The heartbeat
setting is retained but is not a general periodic-work engine. A separate
installation [Decision role](https://docs.formation.texturehq.com/runtime/decision-models.md) handles supported bounded
classifications; when native decisions are off, supported classifiers use a text
model. When enabled — the default for new agents —
[automatic model selection](https://docs.formation.texturehq.com/runtime/adaptive-model-routing.md) selects answer
models from the provider catalog under the saved family and capability filters,
never above the primary's price. Routing does not grant tools or expand a budget.

[Tools](https://docs.formation.texturehq.com/runtime/tools.md) declare their input schema, execution class, capabilities,
and replay policy. Formation validates calls before executing them and records their
outcomes. Enabled integrations expose only the tools authorized for that agent;
credentials belong to the agent or connector install they authenticate.

Memory writes, external writes, shell execution, and connector delivery have
separate persistence and recovery rules. A model's claim that an operation
succeeded is not evidence that it committed.

## Budgets

The current catalog includes workspace tools, so ordinary agents default to the
**work** profile: 60 model calls. Operators can set the agent's iteration limit
between 2 and 120. Tool-call and token allowances scale with that limit; actual
provider usage is recorded separately. The smaller conversation profile is
available to builds without work-class tools.

The default wall-clock backstop is **30 minutes**, independent of iteration
count. An agent override can range from one minute to four hours. A reserved
closing completion removes tools and lets the agent finish or explain its pause.
These are limits on one stretch of work, not a promise that every task completes
within them.

[Prompt admission](https://docs.formation.texturehq.com/runtime/prompt-budget.md) separately bounds each model request.
Older tool results can be compacted, and optional history or memory can be
omitted, while source restrictions remain attached to everything the model
already saw.

## Long tasks, updates, and restart recovery

* [Live steering](https://docs.formation.texturehq.com/runtime/live-steering.md) incorporates requester corrections and
  handles explicit stop commands during a run.
* [Human-authorized continuation](https://docs.formation.texturehq.com/runtime/task-continuation.md) saves task context
  when a run reaches its allowance and lets the requester continue it.
* [Turn checkpoints](https://docs.formation.texturehq.com/runtime/turn-checkpoints.md) let a replacement worker resume
  a crashed run from durable model/tool boundaries.

Within a run, the harness is expected to follow through rather than surface the
first failure: retry a recoverable error with backoff a bounded number of times,
and when a tool is genuinely unavailable, change approach to another authorized
path before returning an error to a person. See the
[follow-through principle](https://docs.formation.texturehq.com/philosophy.md#the-follow-through-principle).

* [Commitments](https://docs.formation.texturehq.com/runtime/commitments.md) track a durable objective across bounded
  attempts; [schedules](https://docs.formation.texturehq.com/runtime/schedules.md) trigger work at configured times.

A recorded effect with an unknown outcome is not blindly repeated after a
restart. Final delivery still passes current audience and source checks.

## Repeated-tool observation

At a completed tool-round checkpoint, Formation saves `tool_repeats.recent`: at most
64 call references and request/result digests for this execution. Three matching
requests and observations mark a **candidate**, not a finding of no progress.
JSON object key order and whitespace do not matter; array order, omitted fields,
number spellings, and non-JSON text do. Interleaved identical calls can match;
changed evidence for the same request resets its streak. Rejected rounds and
recoverable handler errors are included.

This is **observe-only**. It does not add model instructions, suppress a call,
replay a write, extend budgets, or authorize polling. Intentional retries, polling,
and unchanged tests may legitimately be candidates. Existing unknown-effect
reconciliation and authorization remain unchanged. The initial threshold is an
internal observation constant, not a validated stopping policy.

State is scoped to the existing agent-owned run checkpoint and survives checkpoint
resume, but is not carried into a new continuation run. The checkpoint holds a
rolling window, not a permanent detection event stream; older candidates can age
out. There is no new dashboard or external telemetry export. Digests contain no
raw arguments or result text but are **sensitive correlation metadata**, not
anonymization; they retain the checkpoint's access boundary. The detector compares
the observations delivered to the loop (including output handles and recovery
notices), not hidden full results or semantic task progress. Dynamic handles and
changed recovery notices can therefore miss a repeat. Changed working revisions
are recognized only when reflected in arguments or observations.

Active recovery, configurable intervention policy, cross-run tracking, and
cost/quality/false-positive evaluation remain follow-up work under MESH-448 and
MESH-442. No cost reduction is claimed by observation alone.

## Implementation boundary

The shipped execution shape is a **loop**. The `execution_shape` schema also
accepts `graph`, but there is no WorkGraph planner, DAG scheduler, graph-artifact
handoff, or model-visible worker-launch feature. The `worker_tasks` ledger is a
storage foundation only. Do not interpret those schema values or older design
notes as available parallel agent execution.

Implementation: [`internal/turn` (repository)](https://github.com/TextureHQ/formation/tree/main/internal/turn),
[`internal/run` (repository)](https://github.com/TextureHQ/formation/tree/main/internal/run), and
[`internal/app/wire.go` (repository)](https://github.com/TextureHQ/formation/blob/main/internal/app/wire.go).

## Deterministic policy evaluation

The [harness evaluation suite (repository)](https://github.com/TextureHQ/formation/blob/main/docs/runtime/harness-evaluation.md) versions synthetic tool trajectories and compares raw/current compaction policies across input budgets. It runs in the normal Go test suite and guards observe-only repeat detection, checkpoint restoration and admission estimates. It is not live-model coding-task or billing evidence.


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