session

package
v0.10.15 Latest Latest
Warning

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

 Go to latest Published: May 8, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package session provides JSONL session logging, cost tracking, and replay for agent runs.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultPricing = agent.DefaultPricing

DefaultPricing contains built-in pricing for common models. Delegates to agent.DefaultPricing so both packages share one source of truth.

Functions

func NewEvent 

func NewEvent(sessionID string, seq int, eventType agent.EventType, data any) agent.Event

NewEvent creates an Event with the given type and data, auto-assigning the timestamp.

func ReadEvents 

func ReadEvents(path string) ([]agent.Event, error)

ReadEvents reads all events from a session log file.

func Replay 

func Replay(path string, w io.Writer) error

Replay reads a session log and renders a human-readable conversation.

Types

type LLMRequestData 

type LLMRequestData struct {
	Messages          []agent.Message `json:"messages"`
	Tools             []agent.ToolDef `json:"tools,omitempty"`
	Model             string          `json:"model,omitempty"`
	Temperature       *float64        `json:"temperature,omitempty"`
	TopP              *float64        `json:"top_p,omitempty"`
	TopK              *int            `json:"top_k,omitempty"`
	MinP              *float64        `json:"min_p,omitempty"`
	RepetitionPenalty *float64        `json:"repetition_penalty,omitempty"`
	MaxTokens         int             `json:"max_tokens,omitempty"`
	Seed              int64           `json:"seed,omitempty"`
	Stop              []string        `json:"stop,omitempty"`
	Reasoning         agent.Reasoning `json:"reasoning,omitempty"`
	CachePolicy       string          `json:"cache_policy,omitempty"`
	// SamplingSource is the comma-separated list of resolution layers that
	// supplied non-nil sampler fields, in chain order. Values:
	// "catalog", "provider_config", "cli", or combinations like
	// "catalog,provider_config". Empty when all sampler fields were nil
	// (server defaults applied). See ADR-007 §5.
	SamplingSource string `json:"sampling_source,omitempty"`
}

LLMRequestData is the data payload for an llm.request event.

type LLMResponseData 

type LLMResponseData struct {
	Content      string           `json:"content,omitempty"`
	ToolCalls    []agent.ToolCall `json:"tool_calls,omitempty"`
	Usage        agent.TokenUsage `json:"usage"`
	CostUSD      float64          `json:"cost_usd"`
	LatencyMs    int64            `json:"latency_ms"`
	Model        string           `json:"model"`
	FinishReason string           `json:"finish_reason"`
}

LLMResponseData is the data payload for an llm.response event.

type Logger 

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

Logger writes session events to a JSONL file.

func NewLogger 

func NewLogger(dir, sessionID string) *Logger

NewLogger creates a Logger that writes to the given directory. If the directory does not exist, it is created. If creation fails, the logger will silently skip writes (best-effort logging).

func (*Logger) Callback 

func (l *Logger) Callback() agent.EventCallback

Callback returns an EventCallback suitable for agent.Request.Callback.

func (*Logger) Close 

func (l *Logger) Close() error

Close flushes and closes the log file.

func (*Logger) Emit 

func (l *Logger) Emit(eventType agent.EventType, data any)

Emit creates and writes an event with auto-incrementing sequence number.

func (*Logger) Write 

func (l *Logger) Write(e agent.Event)

Write appends a pre-built event to the log file.

type ModelPricing 

type ModelPricing = agent.ModelPricing

ModelPricing holds per-million-token costs for a model. Alias of agent.ModelPricing — kept here for backward compatibility.

type PricingTable 

type PricingTable = agent.PricingTable

PricingTable maps model IDs to their pricing. Alias of agent.PricingTable — kept here for backward compatibility.

type RoutingQualityScan 

type RoutingQualityScan struct {
	TotalRequests  int
	OverrideEvents []agent.Event
}

RoutingQualityScan is the result of walking session logs in a directory to recover routing-quality inputs (ADR-006 §5). TotalRequests counts session.start events whose timestamp falls within window; OverrideEvents holds the raw EventOverride / EventRejectedOverride records, decoding of which is the agent package's responsibility (the payload type lives there).

func ScanRoutingQuality 

func ScanRoutingQuality(logDir string, window *UsageWindow) (*RoutingQualityScan, error)

ScanRoutingQuality walks every .jsonl session log in logDir and produces the inputs needed to recompute routing-quality metrics over window.

The scan is the authoritative data source for windowed reporting because the in-memory ring is bounded and recent-only — it cannot produce historical, cross-restart, or window-bounded views without persisted session logs.

A nil window means "no time filter" (include every session). Sessions without a session.start event are skipped (incomplete logs).

type RoutingStickyState added in v0.10.9 

type RoutingStickyState struct {
	KeyPresent     bool    `json:"key_present,omitempty"`
	Assignment     string  `json:"assignment,omitempty"`
	ServerInstance string  `json:"server_instance,omitempty"`
	Reason         string  `json:"reason,omitempty"`
	Bonus          float64 `json:"bonus"`
}

RoutingStickyState summarizes sticky routing behavior without exposing the raw sticky key.

type RoutingUtilizationState added in v0.10.9 

type RoutingUtilizationState struct {
	Source         string    `json:"source,omitempty"`
	Freshness      string    `json:"freshness,omitempty"`
	ActiveRequests *int      `json:"active_requests,omitempty"`
	QueuedRequests *int      `json:"queued_requests,omitempty"`
	MaxConcurrency *int      `json:"max_concurrency,omitempty"`
	CachePressure  *float64  `json:"cache_pressure,omitempty"`
	ObservedAt     time.Time `json:"observed_at,omitempty"`
}

RoutingUtilizationState carries the live endpoint sample that informed a routing decision.

type SessionEndData 

type SessionEndData struct {
	Status                 agent.Status            `json:"status"`
	Output                 string                  `json:"output"`
	Tokens                 agent.TokenUsage        `json:"tokens"`
	CostUSD                *float64                `json:"cost_usd,omitempty"`
	DurationMs             int64                   `json:"duration_ms"`
	Model                  string                  `json:"model,omitempty"`
	SelectedProvider       string                  `json:"selected_provider,omitempty"`
	SelectedEndpoint       string                  `json:"selected_endpoint,omitempty"`
	SelectedServerInstance string                  `json:"selected_server_instance,omitempty"`
	SelectedRoute          string                  `json:"selected_route,omitempty"`
	Sticky                 RoutingStickyState      `json:"sticky,omitempty"`
	Utilization            RoutingUtilizationState `json:"utilization,omitempty"`
	RequestedHarness       string                  `json:"requested_harness,omitempty"`
	ResolvedHarness        string                  `json:"resolved_harness,omitempty"`
	HarnessSource          string                  `json:"harness_source,omitempty"`
	RequestedModel         string                  `json:"requested_model,omitempty"`
	RequestedModelRef      string                  `json:"requested_model_ref,omitempty"`
	ResolvedModelRef       string                  `json:"resolved_model_ref,omitempty"`
	ResolvedModel          string                  `json:"resolved_model,omitempty"`
	Reasoning              agent.Reasoning         `json:"reasoning,omitempty"`
	AttemptedProviders     []string                `json:"attempted_providers,omitempty"`
	FailoverCount          int                     `json:"failover_count,omitempty"`
	Metadata               map[string]string       `json:"metadata,omitempty"`
	Error                  string                  `json:"error,omitempty"`
}

SessionEndData is the data payload for a session.end event.

type SessionStartData 

type SessionStartData struct {
	Provider               string                  `json:"provider"`
	Model                  string                  `json:"model"`
	SelectedProvider       string                  `json:"selected_provider,omitempty"`
	SelectedEndpoint       string                  `json:"selected_endpoint,omitempty"`
	SelectedServerInstance string                  `json:"selected_server_instance,omitempty"`
	SelectedRoute          string                  `json:"selected_route,omitempty"`
	Sticky                 RoutingStickyState      `json:"sticky,omitempty"`
	Utilization            RoutingUtilizationState `json:"utilization,omitempty"`
	RequestedHarness       string                  `json:"requested_harness,omitempty"`
	ResolvedHarness        string                  `json:"resolved_harness,omitempty"`
	HarnessSource          string                  `json:"harness_source,omitempty"`
	RequestedModel         string                  `json:"requested_model,omitempty"`
	RequestedModelRef      string                  `json:"requested_model_ref,omitempty"`
	ResolvedModelRef       string                  `json:"resolved_model_ref,omitempty"`
	ResolvedModel          string                  `json:"resolved_model,omitempty"`
	Reasoning              agent.Reasoning         `json:"reasoning,omitempty"`
	AttemptedProviders     []string                `json:"attempted_providers,omitempty"`
	FailoverCount          int                     `json:"failover_count,omitempty"`
	WorkDir                string                  `json:"work_dir"`
	MaxIterations          int                     `json:"max_iterations"`
	Prompt                 string                  `json:"prompt"`
	SystemPrompt           string                  `json:"system_prompt,omitempty"`
	Metadata               map[string]string       `json:"metadata,omitempty"`
}

SessionStartData is the data payload for a session.start event.

type ToolCallData 

type ToolCallData struct {
	Tool       string          `json:"tool"`
	Input      json.RawMessage `json:"input"`
	Output     string          `json:"output"`
	DurationMs int64           `json:"duration_ms"`
	Error      string          `json:"error,omitempty"`
}

ToolCallData is the data payload for a tool.call event.

type UsageOptions 

type UsageOptions struct {
	// Since limits the report window. Supported values include today, 7d, 30d,
	// a date range (YYYY-MM-DD..YYYY-MM-DD), or a single start date.
	Since string

	// Now is the reference time for relative windows. Zero means time.Now().
	Now time.Time
}

UsageOptions configures how session logs are aggregated.

type UsageReport 

type UsageReport struct {
	Window *UsageWindow `json:"window,omitempty"`
	Rows   []UsageRow   `json:"rows"`
	Totals UsageRow     `json:"totals"`
}

UsageReport is the aggregate output for a session log scan.

func AggregateUsage 

func AggregateUsage(logDir string, opts UsageOptions) (*UsageReport, error)

AggregateUsage scans JSONL session logs in logDir and aggregates token and cost totals by provider/model.

type UsageRow 

type UsageRow struct {
	Provider            string   `json:"provider"`
	Model               string   `json:"model"`
	Sessions            int      `json:"sessions"`
	SuccessSessions     int      `json:"success_sessions"`
	FailedSessions      int      `json:"failed_sessions"`
	InputTokens         int      `json:"input_tokens"`
	OutputTokens        int      `json:"output_tokens"`
	TotalTokens         int      `json:"total_tokens"`
	DurationMs          int64    `json:"duration_ms"`
	KnownCostUSD        *float64 `json:"known_cost_usd"`
	UnknownCostSessions int      `json:"unknown_cost_sessions"`
	CacheReadTokens     int      `json:"cache_read_tokens"`
	CacheWriteTokens    int      `json:"cache_write_tokens"`
}

UsageRow aggregates usage for one provider/model pair.

func (UsageRow) CacheHitRate 

func (r UsageRow) CacheHitRate() float64

CacheHitRate returns the fraction of input tokens served from cache (0..1).

func (UsageRow) CostPerSuccess 

func (r UsageRow) CostPerSuccess() *float64

CostPerSuccess returns the known cost divided by successful sessions, or nil if there are no successes or cost is unknown.

func (UsageRow) InputTokensPerSecond 

func (r UsageRow) InputTokensPerSecond() float64

InputTokensPerSecond returns the average input-token throughput.

func (UsageRow) OutputTokensPerSecond 

func (r UsageRow) OutputTokensPerSecond() float64

OutputTokensPerSecond returns the average output-token throughput.

func (UsageRow) SuccessRate 

func (r UsageRow) SuccessRate() float64

SuccessRate returns the fraction of sessions that succeeded (0 if no sessions).

type UsageWindow 

type UsageWindow struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

UsageWindow describes the active reporting window.

func ParseUsageWindow 

func ParseUsageWindow(spec string, now time.Time) (*UsageWindow, error)

ParseUsageWindow parses the --since value into a UTC time window.

func (UsageWindow) Contains 

func (w UsageWindow) Contains(ts time.Time) bool

Contains reports whether ts falls within the half-open usage window.

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.