engine

Documentation

Overview

Package engine drives the interactive testagent loop. It picks between a bubbletea TUI (when stdin is a TTY) and a bufio.Scanner-based fallback (when stdin is piped), runs the loop, fires the SessionEnd hook on quit, and returns the exit code.

Index

• func Run(ctx context.Context, g Globals, d Deps) int
• type Deps
• type Globals
• type HookSender

Functions

func Run

func Run(ctx context.Context, g Globals, d Deps) int

Run picks TUI vs scanner based on stdin TTY status, runs the loop until quit/exit, fires SessionEnd, closes MCP, and returns the exit code.

The returned reason for SessionEnd mirrors Claude Code's vocabulary ("logout" for /exit, "other" for SIGINT, EOF, /auto-exit, etc.).

Types

type Deps

type Deps struct {
	Hooks HookSender
	MCP   *mcp.Client
	Slash *slash.Handler
}

Deps are the runtime dependencies the engine drives. All fields are required.

type Globals

type Globals struct {
	Emulator    string // "Claude", "Codex", etc. — vendor type prefix shown in the banner
	Name        string // user-supplied session label (--name)
	SessionID   string
	Resumed     bool
	ThinkDelay  time.Duration // default thinking-spinner duration per turn
	StreamDelay time.Duration // default per-token interval for the response stream
	ExitAfter   int
	AutoExit    time.Duration
	HistoryCap  int    // 0 = unlimited
	StatusLine  string // shown under the banner; empty = omitted
}

Globals holds the per-run configuration shared by the TUI and scanner loops. Values come from the caller's flag set; the engine treats them as immutable for the lifetime of Run.

type HookSender

type HookSender interface {
	OnPrompt(ctx context.Context, prompt, sessionTitle string) error
	OnPreToolUse(ctx context.Context, toolUseID, toolName string, toolInput any) error
	OnPostToolUse(ctx context.Context, toolUseID, toolName string, toolInput, toolResponse any, durationMs int64) error
	OnStop(ctx context.Context, lastAssistantMessage string, stopHookActive bool) error
	OnSessionStart(ctx context.Context, source string) error
	OnSessionEnd(ctx context.Context, reason string) error
	OnPreCompact(ctx context.Context, trigger string) error
	OnPostCompact(ctx context.Context, trigger string) error
}

HookSender is the engine's interface to vendor-specific hook delivery. claude's HTTP-POST sender (internal/hooks) and codex's TOML shell- command runner (internal/codexhooks) both satisfy it. Defined here at the consumer site per Go conventions.

OnPreToolUse and OnPostToolUse are included so the slash dispatcher (which fires both during a /fake-tool + /fake-tool-result cycle) can take a value of this same type rather than a separate narrower interface — Go interface assignment is structural, so a value held as HookSender keeps both tool-use methods callable.