calllog

Documentation

Overview

Package calllog appends structured call records to <repo>/.suitcode/calls.jsonl. All fields use relative paths only — no code content or absolute paths are ever written.

Index

• Constants
• type Logger
  • func New(repoPath string) (*Logger, error)
  • func (l *Logger) Append(r Record) error
  • func (l *Logger) Export(outputPath string) error
  • func (l *Logger) LoadAll() ([]Record, error)
  • func (l *Logger) Path() string
  • func (l *Logger) PrintAggregateSummary(w io.Writer, last int) error
  • func (l *Logger) PrintCallLog(w io.Writer, last int) error
  • func (l *Logger) PrintSummary(w io.Writer, last int) error
  • func (l *Logger) SetLastFeedback(feedback string) error
  • func (l *Logger) UnratedCount() int
• type Record

Constants

const FileName = "calls.jsonl"

FileName is the name of the JSONL log file inside the .suitcode directory.

Types

type Logger

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

Logger appends Records to <repoPath>/.suitcode/calls.jsonl. It is safe for concurrent use.

func New

func New(repoPath string) (*Logger, error)

New creates a Logger for the given repository root. The .suitcode directory is created if it does not exist.

func (*Logger) Append

func (l *Logger) Append(r Record) error

Append writes r as a JSON line. TS is set to now (UTC) if empty. Callers should treat failures as non-fatal warnings; logging must never block a feature call.

func (*Logger) Export

func (l *Logger) Export(outputPath string) error

Export packages the call log into a zip archive at outputPath. The zip contains only the JSONL file — no code content or absolute paths. outputPath is created or truncated; its parent directory must already exist.

func (*Logger) LoadAll

func (l *Logger) LoadAll() ([]Record, error)

LoadAll reads all records from the JSONL file in chronological order. Returns an empty slice if the file does not exist. Malformed lines are silently skipped.

func (*Logger) Path

func (l *Logger) Path() string

Path returns the absolute path to the JSONL file.

func (*Logger) PrintAggregateSummary

func (l *Logger) PrintAggregateSummary(w io.Writer, last int) error

PrintAggregateSummary writes a condensed, human-readable session summary to w. It aggregates the most recent 'last' records (0 = all) by feature and prints per-feature stats plus a problems section. Output is designed to be copy-pasteable in ~15 lines. Uses ASCII-only characters for Windows clipboard compatibility.

func (*Logger) PrintCallLog

func (l *Logger) PrintCallLog(w io.Writer, last int) error

PrintCallLog writes a detailed per-call log to w, including seed files and limitation kinds. Pass last = 0 to show all records.

func (*Logger) PrintSummary

func (l *Logger) PrintSummary(w io.Writer, last int) error

PrintSummary writes a human-readable tabular summary of the most recent records to w. Pass last = 0 to show all records.

func (*Logger) SetLastFeedback

func (l *Logger) SetLastFeedback(feedback string) error

SetLastFeedback updates the most recent call record with the given feedback value ("good" or "bad") and records the timestamp. It reads all records, patches the last one, and atomically rewrites the file. Returns an error when no records exist yet.

func (*Logger) UnratedCount

func (l *Logger) UnratedCount() int

UnratedCount returns the number of content-producing feature calls at the tail of the log that have not yet received a feedback rating. The count resets to 0 after every rated call. Returns 0 when the log is empty or the most recent feature call is already rated.

type Record

type Record struct {
	TS                 string   `json:"ts"`
	Feature            string   `json:"feature"`
	SeedFiles          []string `json:"seed_files,omitempty"`
	FilesReturned      []string `json:"files_returned,omitempty"`
	CandidatesTotal    int      `json:"candidates_total"`
	FilesIncluded      int      `json:"files_included"`
	CompressionRatio   float64  `json:"compression_ratio"`
	BudgetRequested    int      `json:"budget_requested"`
	BudgetUsed         int      `json:"budget_used"`
	LatencyMs          int64    `json:"latency_ms"`
	ImportEdgesScanned int      `json:"import_edges_scanned"`
	LspEnhanced        bool     `json:"lsp_enhanced"`

	// HasError is true when the feature call failed to produce a response.
	// The call is still recorded so the summary can surface error rates.
	HasError bool `json:"has_error,omitempty"`

	// LimitationCount is the number of Limitation notices in the response.
	// A non-zero value means the answer is degraded in some way (missing
	// import graph, heuristic fallbacks, unresolved files, etc.).
	LimitationCount int `json:"limitation_count,omitempty"`

	// LimitationKinds lists the Kind of each Limitation in the response.
	// Use this to distinguish advisory limitations (expected, e.g. "contextual_trimmed")
	// from quality degradations (e.g. "no_lang_provider", "file_not_found").
	// Populated alongside LimitationCount; nil on older records.
	LimitationKinds []string `json:"limitation_kinds,omitempty"`

	// Feedback records whether the agent found the response helpful.
	// Set via "suitcode <path> feedback good|bad".
	// Empty when no feedback has been given for this call.
	Feedback string `json:"feedback,omitempty"`

	// FeedbackAt is the RFC3339 timestamp when feedback was recorded.
	FeedbackAt string `json:"feedback_at,omitempty"`
}

Record is one feature-call entry in the call log. All path fields are relative to the repository root. Privacy invariant: never include file content, absolute paths, or user-identifiable data.