loop

Documentation

Overview

Package loop implements the work loop of §6.4 and its instrumentation (adenda A.2): cada intento escribe una línea en .devclean/runs/<id>/attempts.jsonl. Ese archivo es la única fuente de las métricas y del parte de datos (§6.7); nada se recalcula leyendo el repo después.

Index

• Constants
• func ParseTestCounts(salida string) (pasaron, fallaron *int)
• func RunsDir(root string) string
• type Agent
• type Attempt
  • func ReadAttempts(root, id string) ([]Attempt, error)
• type Examinador
• type Options
• type Outcome
  • func Run(ctx context.Context, o Options) (Outcome, error)
• type Request
• type Result
• type Tokens

Constants

const DefaultTimeout = 5 * time.Minute

DefaultTimeout is the fallback when Options no fija un timeout.

Functions

func ParseTestCounts

func ParseTestCounts(salida string) (pasaron, fallaron *int)

ParseTestCounts parses test pass/fail counts from test runner output. Returns (nil, nil) when the format is not recognized — callers must not invent numbers (adenda A.2).

func RunsDir

func RunsDir(root string) string

RunsDir returns the runs directory of the repository at root.

Types

type Agent

type Agent interface {
	Name() string
	Run(ctx context.Context, req Request) (Result, error)
}

Agent es lo mínimo que el bucle pide al ejecutor: una invocación por intento y el gasto de tokens que produjo. La interfaz se declara aquí, del lado del consumidor; los adaptadores de internal/executor la satisfacen con un shim en cmd/run, sin que el bucle dependa de un paquete en obra.

type Attempt

type Attempt struct {
	Intento                  int       `json:"intento"`
	Inicio                   time.Time `json:"inicio"`
	Fin                      time.Time `json:"fin"`
	SalidaCodigo             *int      `json:"salida_codigo"`
	TestsPasaron             *int      `json:"tests_pasaron"`
	TestsFallaron            *int      `json:"tests_fallaron"`
	ArchivosTocados          []string  `json:"archivos_tocados"`
	SimbolosExportados       *[]string `json:"simbolos_exportados"`
	LineasMas                int       `json:"lineas_mas"`
	LineasMenos              int       `json:"lineas_menos"`
	RevertidosFueraDeAlcance []string  `json:"revertidos_fuera_de_alcance"`
	Tokens                   Tokens    `json:"tokens"`
	Modelo                   string    `json:"modelo"`
}

Attempt is one line of attempts.jsonl. Los campos que el bucle no puede derivar con certeza van en nil, que en JSON es null: un número que no se pudo medir nunca se inventa (adenda A.2).

func ReadAttempts

func ReadAttempts(root, id string) ([]Attempt, error)

ReadAttempts returns every recorded attempt of a task, oldest first. A task that never ran has no attempts (not an error).

type Examinador

type Examinador interface {
	Run(ctx context.Context, roomPath string) (bool, error)
}

Examinador genera la suite de pruebas ciega antes de que el implementador empiece (§6.8). La interfaz vive en loop para evitar un ciclo de importación con el paquete examiner.

type Options

type Options struct {
	Agent          Agent
	Root           string
	Room           room.Room
	Task           task.Task
	Model          string
	Base           string        // rama base para el diff de símbolos
	PatronesPrueba []string      // rutas de prueba que nunca se editan
	AgentTimeout   time.Duration // timeout de cada invocación del agente
	PruebaTimeout  time.Duration // timeout de cada listo_cuando
	Env            []string      // variables propias del cuarto (PORT, ...)

	// Interfaces son las firmas congeladas de las tareas hermanas que
	// esta consume (§6.10), ya resueltas por el que llama. Sin esto el
	// agente inventa la firma: las tareas de una misma oleada corren en
	// cuartos separados y no pueden leerse entre sí.
	Interfaces []string

	// Constitucion es el contenido de .devclean/constitution.md (§6.11),
	// ya cargado por quien llama. Si está vacío, no se inyecta nada.
	Constitucion string

	// Examinador, si no es nil, se invoca una vez antes del bucle del
	// implementador para escribir la suite visible y sellar la oculta
	// (§6.8). Si falla, el bucle continúa sin pruebas ciegas.
	Examinador Examinador
}

Options lleva las dependencias del bucle.

type Outcome

type Outcome struct {
	Verde       bool   `json:"verde"`
	Intentos    int    `json:"intentos"`
	UltimoError string `json:"ultimo_error,omitempty"`
	Pregunta    string `json:"pregunta,omitempty"`
}

Outcome es el resultado de correr el bucle sobre una tarea.

func Run

func Run(ctx context.Context, o Options) (Outcome, error)

Run dirige el bucle de §6.4 e instrumenta cada intento (adenda A.2). Devuelve el Outcome; solo error si el mecanismo falla (no si la tarea se agotó: detenerse es un resultado válido, no un fallo).

type Request

type Request struct {
	RoomPath     string
	Prompt       string
	AllowedGlobs []string
	Model        string
	Timeout      time.Duration
	Env          []string
}

Request es una invocación del agente dentro de su cuarto.

type Result

type Result struct {
	Stdout   string
	Text     string // respuesta textual del agente (campo "result" del JSON de claude)
	ExitCode int
	Tokens   Tokens
}

Result es lo que devolvió una invocación.

type Tokens

type Tokens struct {
	Entrada int `json:"entrada"`
	Salida  int `json:"salida"`
}

Tokens is the token spend of one attempt.