loop.go

package reference

import (
	"context"
	"errors"
	"fmt"
	"time"
)

// AgentLoopConfig configures the execution parameters for an Agentic Loop.
type AgentLoopConfig struct {
	MaxSteps       int
	EnergyBudget   int
	StepTimeout    time.Duration
	ExitOnGoalPass bool
}

// ToolCall represents a structured tool invocation request from the model.
type ToolCall struct {
	Name       string                 `json:"name"`
	Action     string                 `json:"action"`
	Arguments  map[string]interface{} `json:"arguments"`
	EnergyCost int                    `json:"energy_cost"`
}

// StepResult represents the observation outcome returned to the model.
type StepResult struct {
	StepIndex  int         `json:"step_index"`
	Output     string      `json:"output"`
	Err        error       `json:"err,omitempty"`
	GoalPassed bool        `json:"goal_passed"`
}

// AgenticLoopKernel manages energy-metered, step-bounded execution loops.
type AgenticLoopKernel struct {
	config      AgentLoopConfig
	energySpent int
	currentStep int
}

// NewAgenticLoopKernel initializes a new Agentic Loop instance.
func NewAgenticLoopKernel(cfg AgentLoopConfig) *AgenticLoopKernel {
	if cfg.MaxSteps <= 0 {
		cfg.MaxSteps = 20
	}
	if cfg.EnergyBudget <= 0 {
		cfg.EnergyBudget = 1000
	}
	if cfg.StepTimeout == 0 {
		cfg.StepTimeout = 30 * time.Second
	}
	return &AgenticLoopKernel{config: cfg}
}

// ExecuteStep runs a single perception-action cycle within energy & step boundaries.
func (k *AgenticLoopKernel) ExecuteStep(ctx context.Context, call ToolCall, executor func(context.Context, ToolCall) (string, bool, error)) (*StepResult, error) {
	if k.currentStep >= k.config.MaxSteps {
		return nil, fmt.Errorf("agentic loop error: step limit reached (%d/%d)", k.currentStep, k.config.MaxSteps)
	}

	cost := call.EnergyCost
	if cost <= 0 {
		cost = 10
	}

	if k.energySpent+cost > k.config.EnergyBudget {
		return nil, fmt.Errorf("agentic loop error: energy budget depleted (%d/%d spent)", k.energySpent, k.config.EnergyBudget)
	}

	k.currentStep++
	k.energySpent += cost

	stepCtx, cancel := context.WithTimeout(ctx, k.config.StepTimeout)
	defer cancel()

	output, goalPassed, err := executor(stepCtx, call)
	
	res := &StepResult{
		StepIndex:  k.currentStep,
		Output:     output,
		Err:        err,
		GoalPassed: goalPassed,
	}

	return res, nil
}