debug

package
v0.1.0-alpha.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 8, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const MaxTruncateLen = 500

MaxTruncateLen is the default max length for truncating tool input/output in logs.

Variables

This section is empty.

Functions

func CreateSessionDir 

func CreateSessionDir(logDir string) (string, error)

CreateSessionDir creates a uniquely-named session directory under logDir. Format: 2006-01-02_15-04-05_{8-hex-chars}. The random suffix eliminates naming collisions without a stat→mkdir race window. Returns empty string if logDir is empty.

func RotateLogs 

func RotateLogs(logDir string, maxAge time.Duration) error

RotateLogs removes old session directories and legacy JSONL files from logDir. Session directories and JSONL files older than maxAge are deleted. It is safe to call even if logDir does not exist.

func SanitizeID 

func SanitizeID(id string) string

SanitizeID returns the last 8 characters of an ID, filtering non-alphanumeric characters.

func SessionLogDirFromCtx 

func SessionLogDirFromCtx(ctx context.Context) string

SessionLogDirFromCtx retrieves the session log directory from the context. Returns empty string if not set.

func Truncate 

func Truncate(s string, max int) string

Truncate shortens a string to max length, appending a truncation marker if needed.

func WithSessionLogDir 

func WithSessionLogDir(ctx context.Context, dir string) context.Context

WithSessionLogDir stores the session log directory path in the context.

Types

type AssistantMessageData 

type AssistantMessageData struct {
	Content      string `json:"content"`
	FinishReason string `json:"finish_reason,omitempty"`
}

AssistantMessageData captures assistant response content.

type AssistantThinkingData 

type AssistantThinkingData struct {
	Thinking string `json:"thinking"`
}

AssistantThinkingData captures chain-of-thought reasoning.

type BudgetDecisionData 

type BudgetDecisionData struct {
	Action          string  `json:"action"` // "allow" / "deny" / "hard_stop"
	Reason          string  `json:"reason"`
	TokenUsageRatio float64 `json:"token_usage_ratio,omitempty"`
	CostAccumulated float64 `json:"cost_accumulated,omitempty"`
	HasNudge        bool    `json:"has_nudge"`
}

BudgetDecisionData records a budget check decision.

type CompactData 

type CompactData struct {
	MessagesBefore int `json:"messages_before"`
	TokensBefore   int `json:"tokens_before"`
}

CompactData records a compaction event.

type ErrorData 

type ErrorData struct {
	Message string `json:"message"`
	Context string `json:"context,omitempty"`
}

ErrorData records an error event.

type EventType 

type EventType string

EventType enumerates the kinds of debug log entries. 

const (
	EventSessionStart      EventType = "session_start"
	EventSessionEnd        EventType = "session_end"
	EventSessionCompact    EventType = "session_compact"
	EventLLMRequest        EventType = "llm_request"
	EventLLMResponse       EventType = "llm_response"
	EventToolStart         EventType = "tool_start"
	EventToolEnd           EventType = "tool_end"
	EventLoopIteration     EventType = "loop_iteration"
	EventError             EventType = "error"
	EventUserMessage       EventType = "user_message"
	EventAssistantMessage  EventType = "assistant_message"
	EventAssistantThinking EventType = "assistant_thinking"
	EventStopDecision      EventType = "stop_decision"
	EventBudgetDecision    EventType = "budget_decision"
)

type LLMRequestData 

type LLMRequestData struct {
	Model        string `json:"model"`
	MessageCount int    `json:"message_count"`
	ToolCount    int    `json:"tool_count"`
}

LLMRequestData captures metadata about an API call being sent.

type LLMResponseData 

type LLMResponseData struct {
	Model               string  `json:"model"`
	InputTokens         int64   `json:"input_tokens"`
	OutputTokens        int64   `json:"output_tokens"`
	CacheCreationTokens int64   `json:"cache_creation_tokens,omitempty"`
	CacheReadTokens     int64   `json:"cache_read_tokens,omitempty"`
	LatencyMs           int64   `json:"latency_ms"`
	Cost                float64 `json:"cost"`
	CostKnown           bool    `json:"cost_known"`
	FinishReason        string  `json:"finish_reason"`
	ToolCallCount       int     `json:"tool_call_count,omitempty"`
}

LLMResponseData captures the outcome of an API call.

type LogEntry 

type LogEntry struct {
	Timestamp string    `json:"ts"`
	SessionID string    `json:"session_id"`
	Type      EventType `json:"type"`
	AgentName string    `json:"agent,omitempty"`
	SubAgent  bool      `json:"sub_agent,omitempty"`
	Iteration int       `json:"iteration,omitempty"`
	Data      any       `json:"data,omitempty"`
}

LogEntry is the base envelope for every JSONL line.

type SessionEndData 

type SessionEndData struct {
	DurationMs int64 `json:"duration_ms"`
	Iterations int   `json:"iterations"`
}

SessionEndData records session end metadata.

type SessionLogger 

type SessionLogger struct {
	// contains filtered or unexported fields
}

SessionLogger writes structured JSONL to a session-specific log file. All methods are nil-safe — calling any method on a nil receiver is a no-op.

func NewMainAgentLogger 

func NewMainAgentLogger(sessionDir, sessionID string) (*SessionLogger, error)

NewMainAgentLogger creates a logger for the main agent, writing to agent.log (append mode).

func NewSessionLogger 

func NewSessionLogger(sessionDir, fileName, sessionID, agentName string, subAgent bool, appendMode bool) (*SessionLogger, error)

NewSessionLogger creates a logger that writes to sessionDir/fileName. Returns nil if sessionDir is empty (disabled).

func NewSubAgentLogger 

func NewSubAgentLogger(sessionDir, sessionID, agentName, taskID string) (*SessionLogger, error)

NewSubAgentLogger creates a logger for a sub-agent, writing to subagent-{name}-{shortID}.log.

func (*SessionLogger) Close 

func (l *SessionLogger) Close()

Close closes the underlying log file.

func (*SessionLogger) LogAssistantMessage 

func (l *SessionLogger) LogAssistantMessage(d AssistantMessageData)

LogAssistantMessage records an assistant response with full content.

func (*SessionLogger) LogAssistantThinking 

func (l *SessionLogger) LogAssistantThinking(d AssistantThinkingData)

LogAssistantThinking records chain-of-thought reasoning.

func (*SessionLogger) LogBudgetDecision 

func (l *SessionLogger) LogBudgetDecision(d BudgetDecisionData)

LogBudgetDecision records a budget check decision.

func (*SessionLogger) LogCompact 

func (l *SessionLogger) LogCompact(d CompactData)

LogCompact records a message history compaction event.

func (*SessionLogger) LogError 

func (l *SessionLogger) LogError(d ErrorData)

LogError records an error event.

func (*SessionLogger) LogLLMRequest 

func (l *SessionLogger) LogLLMRequest(d LLMRequestData)

LogLLMRequest records an outgoing LLM API call.

func (*SessionLogger) LogLLMResponse 

func (l *SessionLogger) LogLLMResponse(d LLMResponseData)

LogLLMResponse records the result of an LLM API call.

func (*SessionLogger) LogSessionEnd 

func (l *SessionLogger) LogSessionEnd()

LogSessionEnd records the end of a session.

func (*SessionLogger) LogSessionStart 

func (l *SessionLogger) LogSessionStart(d SessionStartData)

LogSessionStart records the beginning of a session.

func (*SessionLogger) LogStopDecision 

func (l *SessionLogger) LogStopDecision(d StopDecisionData)

LogStopDecision records a stop controller policy evaluation.

func (*SessionLogger) LogToolEnd 

func (l *SessionLogger) LogToolEnd(d ToolEventData)

LogToolEnd records the completion of a tool execution.

func (*SessionLogger) LogToolStart 

func (l *SessionLogger) LogToolStart(d ToolEventData)

LogToolStart records the beginning of a tool execution.

func (*SessionLogger) LogUserMessage 

func (l *SessionLogger) LogUserMessage(d UserMessageData)

LogUserMessage records a user message with full content.

func (*SessionLogger) SetIteration 

func (l *SessionLogger) SetIteration(n int)

SetIteration updates the current loop iteration counter.

type SessionStartData 

type SessionStartData struct {
	Model string `json:"model"`
}

SessionStartData records session start metadata.

type StopDecisionData 

type StopDecisionData struct {
	PolicyName  string         `json:"policy_name"`
	Action      string         `json:"action"` // "continue" / "terminate"
	Code        string         `json:"code"`
	Reason      string         `json:"reason"`
	Diagnostics map[string]any `json:"diagnostics,omitempty"`
}

StopDecisionData records a StopController policy evaluation.

type TUIFrameMeta 

type TUIFrameMeta struct {
	Reason                    string
	State                     string
	Width                     int
	Height                    int
	Fullscreen                bool
	ResizeEpoch               int
	MainScreenViewportOwned   bool
	MainScreenResetPending    bool
	MainScreenResetApplied    bool
	FlushedAnchor             string
	LiveTailAnchor            string
	OwnedStartAnchor          string
	StreamFlush               string
	OwnedStreamFlush          string
	MainScreenResetReason     string
	MainScreenSliceAnchor     string
	MainScreenPrevLines       int
	MainScreenNextLines       int
	MainScreenFrameLines      int
	MainScreenViewportHeight  int
	MainScreenRendererEnabled bool
	MainScreenResetMode       string
	MainScreenFrameSeq        int64
	MainScreenFullReset       bool
	MainScreenOffscreenReset  bool
}

TUIFrameMeta describes the rendering context for a TUI frame entry.

type TUITrace 

type TUITrace struct {
	// contains filtered or unexported fields
}

TUITrace captures TUI output and readable frame snapshots for debugging. All methods are nil-safe.

func NewTUITrace 

func NewTUITrace(sessionDir string, fullscreen bool) (*TUITrace, error)

NewTUITrace creates log writers under sessionDir: - tui.output.log: escaped terminal output stream - tui.frames.log: ANSI-stripped readable frame snapshots

Returns nil when sessionDir is empty.

func (*TUITrace) Close 

func (t *TUITrace) Close() error

Close closes both trace files.

func (*TUITrace) LogFrame 

func (t *TUITrace) LogFrame(meta TUIFrameMeta, rendered string)

LogFrame records a readable frame snapshot. Duplicate consecutive frames are skipped.

func (*TUITrace) LogScrollback 

func (t *TUITrace) LogScrollback(meta TUIFrameMeta, rendered string)

LogScrollback records readable text that has been committed to terminal scrollback.

func (*TUITrace) WrapOutput 

func (t *TUITrace) WrapOutput(dst io.Writer) io.Writer

WrapOutput returns an io.Writer that mirrors Bubble Tea terminal output into tui.output.log while preserving original writes to dst.

type ToolEventData 

type ToolEventData struct {
	ToolName        string         `json:"tool_name"`
	ToolCallID      string         `json:"tool_call_id"`
	Input           string         `json:"input,omitempty"`
	Output          string         `json:"output,omitempty"`
	DurationMs      int64          `json:"duration_ms,omitempty"`
	IsError         bool           `json:"is_error,omitempty"`
	Error           string         `json:"error,omitempty"`
	MetadataSummary map[string]any `json:"metadata_summary,omitempty"`
}

ToolEventData captures a tool call start or end.

type UserMessageData 

type UserMessageData struct {
	Content string `json:"content"`
}

UserMessageData captures user input content.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.