runloop

Documentation

Overview

Package runloop coordinates repeated agent turns and stop conditions.

Index

• func CompactHookPayload(source string, sessionID string, messages int, keep int) string
• func CompactMessages(messages []anthropic.Message, keep int) []anthropic.Message
• func MarshalToolInput(raw json.RawMessage) string
• func ValidateTurnResult(result TurnResult) error
• type BudgetExceededError
  • func (e BudgetExceededError) Error() string
• type MessageUsage
• type ModelClient
• type Runner
  • func (r Runner) Run(ctx context.Context, previous []anthropic.Message, input string) (TurnResult, error)
  • func (r Runner) RunWithUserContent(ctx context.Context, previous []anthropic.Message, ...) (TurnResult, error)
• type ToolCall
• type TranscriptContractError
  • func (e TranscriptContractError) Error() string
• type TranscriptIssue
• type TranscriptReport
  • func ValidateTranscript(messages []anthropic.Message) TranscriptReport
• type TurnResult

Functions

func CompactHookPayload

func CompactHookPayload(source string, sessionID string, messages int, keep int) string

CompactHookPayload returns the JSON payload sent to pre-compaction hooks.

func CompactMessages

func CompactMessages(messages []anthropic.Message, keep int) []anthropic.Message

CompactMessages replaces older messages with a synthetic summary while preserving the most recent keep messages verbatim.

func MarshalToolInput

func MarshalToolInput(raw json.RawMessage) string

MarshalToolInput renders a raw tool input object for logging and callbacks.

func ValidateTurnResult

func ValidateTurnResult(result TurnResult) error

ValidateTurnResult checks the transcript contained in a completed run result.

Types

type BudgetExceededError

type BudgetExceededError struct {
	LimitUSD float64
	CostUSD  float64
}

BudgetExceededError reports that a turn reached the configured spending cap.

func (BudgetExceededError) Error

func (e BudgetExceededError) Error() string

type MessageUsage

type MessageUsage struct {
	MessageIndex int             `json:"message_index"`
	Usage        anthropic.Usage `json:"usage"`
}

MessageUsage links provider usage metadata to the assistant message that produced it.

type ModelClient

type ModelClient interface {
	Stream(context.Context, anthropic.Request, func(string)) (anthropic.AssistantMessage, error)
}

ModelClient streams one Anthropic-compatible request and returns the final assistant message.

type Runner

type Runner struct {
	Config           config.Config
	Client           ModelClient
	Tools            *tools.Registry
	Prompter         *tools.Prompter
	Hooks            hooks.Runner
	HookPromptRunner hooks.PromptRunner
	Workspace        string
	SessionID        string
	Out              io.Writer
	System           string
	OnToolStart      func(ToolCall)
	OnToolUse        func(ToolCall)
	MaxBudgetUSD     float64
	PriorCostUSD     float64
}

Runner coordinates model streaming, tool execution, hooks, and compaction for a single user prompt.

func (Runner) Run

func (r Runner) Run(ctx context.Context, previous []anthropic.Message, input string) (TurnResult, error)

Run submits input with prior messages, executes tool loops until the model stops, and returns the updated conversation state.

func (Runner) RunWithUserContent

func (r Runner) RunWithUserContent(ctx context.Context, previous []anthropic.Message, content []anthropic.ContentBlock, input string) (TurnResult, error)

RunWithUserContent submits structured user content with prior messages, executes tool loops until the model stops, and returns the updated conversation state. The plain input is still used for hooks and diagnostics.

type ToolCall

type ToolCall struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Input   string `json:"input"`
	Output  string `json:"output"`
	IsError bool   `json:"is_error"`
}

ToolCall records one tool invocation and the result returned to the model.

type TranscriptContractError

type TranscriptContractError struct {
	Report TranscriptReport
}

TranscriptContractError reports a malformed transcript produced by the run loop or supplied to a compatibility harness.

func (TranscriptContractError) Error

func (e TranscriptContractError) Error() string

type TranscriptIssue

type TranscriptIssue struct {
	MessageIndex int    `json:"message_index"`
	BlockIndex   int    `json:"block_index,omitempty"`
	Code         string `json:"code"`
	Message      string `json:"message"`
}

TranscriptIssue describes one Anthropic message transcript contract violation.

type TranscriptReport

type TranscriptReport struct {
	Valid           bool              `json:"valid"`
	MessageCount    int               `json:"message_count"`
	ToolUseCount    int               `json:"tool_use_count"`
	ToolResultCount int               `json:"tool_result_count"`
	Issues          []TranscriptIssue `json:"issues,omitempty"`
}

TranscriptReport summarizes structural compatibility checks for a model transcript.

func ValidateTranscript

func ValidateTranscript(messages []anthropic.Message) TranscriptReport

ValidateTranscript checks the strict Claude-style tool pairing contract used by Codog's run loop: assistant tool_use blocks must have unique IDs, each must be answered by one user tool_result, and no assistant turn may appear while tool results are still pending.

type TurnResult

type TurnResult struct {
	Messages         []anthropic.Message `json:"messages"`
	MessageUsages    []MessageUsage      `json:"message_usages,omitempty"`
	ToolCalls        []ToolCall          `json:"tool_calls,omitempty"`
	StopHookFeedback []string            `json:"stop_hook_feedback,omitempty"`
	Iterations       int                 `json:"iterations"`
}

TurnResult is the complete state produced by one runner invocation.