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

# Package reference: loop

> The agent loop, chunk model, and tool interface that drive hrns.

## Purpose

The `loop` package owns the conversation cycle between the model and your tools.

## Main types

### `ToolArgument`

```go theme={null}
type ToolArgument struct {
    Name, Type string
}
```

This is the package's minimal schema language for tool arguments.

### `Tool`

```go theme={null}
type Tool interface {
    Description() string
    Arguments() []ToolArgument
    Call(args map[string]any) string
}
```

If you want the model to call into application code, this is the interface you implement.

### `SimpleTool`

Use `NewSimpleTool(...)` when a closure is enough and you do not need a custom type.

### `Loop`

Created with:

```go theme={null}
loop.New(openAIClient, tools)
```

It stores the client, the tool map, the last completed message history, and a chunk channel.

## `RunLoop`

`RunLoop(ctx, messages, model)` does the core work:

1. translates tools into function schemas
2. starts a streamed chat completion with the `messages` slice you passed in
3. emits output chunks while streaming
4. accumulates the final assistant message and any tool calls
5. executes tool calls and appends tool messages
6. repeats until the assistant turn finishes without tool calls

When the run completes, it stores the final messages and emits `ChunkTypeEnd`.

## Chunk types

The loop emits these chunk types:

* `message`
* `reasoning`
* `error`
* `tool_call_start`
* `tool_call_error`
* `tool_call_result`
* `end`

These are UI-facing events. The bundled TUI uses them to decide what to print.

## Important behavior details

* Every declared tool argument is marked as required.
* Tool calls are executed synchronously.
* Tool results are appended as `tool` role messages.
* Unknown tools and invalid tool-call JSON become error strings fed back into the conversation.
* Reasoning chunks are currently read from `delta.Extra["reasoning"]` when present.

## Good fit

This package is a good fit when you want a tiny, inspectable agent loop rather than a framework with lots of policy baked in.