monitor

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Apr 3, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package monitor provides the agent state machine, metrics, and event fan-out.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentEvent 

type AgentEvent struct {
	Type      AgentEventType `json:"type"`
	Timestamp time.Time      `json:"timestamp"`
	Data      any            `json:"data,omitempty"`
}

AgentEvent is a normalized event from the termmux event pipeline. This maps to internal/agent.AgentEvent types but is independently defined for the termmux context (3rd party CLI event normalization).

func (*AgentEvent) UnmarshalJSON 

func (e *AgentEvent) UnmarshalJSON(b []byte) error

UnmarshalJSON deserializes an AgentEvent, using the Type field to reconstruct the correct typed Data payload instead of a generic map.

type AgentEventType 

type AgentEventType string

AgentEventType identifies the kind of event. 

const (
	EventSessionStarted      AgentEventType = "session_started"
	EventSessionEnded        AgentEventType = "session_ended"
	EventTurnCompleted       AgentEventType = "turn_completed"
	EventToolStarted         AgentEventType = "tool_started"
	EventToolCompleted       AgentEventType = "tool_completed"
	EventApprovalRequested   AgentEventType = "approval_requested"
	EventPermissionGranted   AgentEventType = "permission_granted"
	EventPermissionDenied    AgentEventType = "permission_denied"
	EventCompactionStarted   AgentEventType = "compaction_started"
	EventCompactionCompleted AgentEventType = "compaction_completed"
	EventAgentMessage        AgentEventType = "agent_message"
	EventStateChange         AgentEventType = "state_change"
)

type AgentMessageData 

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

AgentMessageData carries assistant message content.

type AgentMonitor 

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

AgentMonitor processes normalized events, maintains the state machine, tracks metrics, and fans out events to subscribers.

func NewAgentMonitor 

func NewAgentMonitor(opts ...MonitorOption) *AgentMonitor

NewAgentMonitor creates and starts a new monitor.

func (*AgentMonitor) Close 

func (m *AgentMonitor) Close()

Close shuts down the monitor. Safe to call multiple times.

func (*AgentMonitor) Metrics 

func (m *AgentMonitor) Metrics() Metrics

Metrics returns a snapshot of accumulated metrics.

func (*AgentMonitor) State 

func (m *AgentMonitor) State() (State, SubState)

State returns the current state and sub-state.

func (*AgentMonitor) StateChangedAt 

func (m *AgentMonitor) StateChangedAt() time.Time

StateChangedAt returns the timestamp of the last state change.

func (*AgentMonitor) Submit 

func (m *AgentMonitor) Submit(evt AgentEvent)

Submit sends an event to the monitor for processing. Non-blocking: drops the event if the buffer is full.

func (*AgentMonitor) Subscribe 

func (m *AgentMonitor) Subscribe(ch chan<- AgentEvent) (int, func())

Subscribe registers a channel to receive events. Returns an ID and an unsubscribe function. The channel must be buffered — events are dropped for slow subscribers.

func (*AgentMonitor) WaitStateChange 

func (m *AgentMonitor) WaitStateChange() <-chan struct{}

WaitStateChange returns a channel that is closed when the state changes. Callers should call State() first, then wait on the returned channel for changes.

type ApprovalRequestedData 

type ApprovalRequestedData struct {
	ToolName string          `json:"tool_name"`
	CallID   string          `json:"call_id,omitempty"`
	Payload  json.RawMessage `json:"payload,omitempty"`
}

ApprovalRequestedData carries tool permission request info.

type Metrics 

type Metrics struct {
	InputTokens  int64
	OutputTokens int64
	TotalCostUSD float64
	TurnCount    int64
	ToolCounts   map[string]int64
}

Metrics is a snapshot of accumulated metrics.

type MonitorOption 

type MonitorOption func(*AgentMonitor)

MonitorOption configures the AgentMonitor.

func WithEventWriter 

func WithEventWriter(fn func(AgentEvent) error) MonitorOption

WithEventWriter sets a function called for each processed event (e.g., JSONL persistence).

func WithIdleThreshold 

func WithIdleThreshold(d time.Duration) MonitorOption

WithIdleThreshold sets the idle timeout duration.

type SessionEndedData 

type SessionEndedData struct {
	Reason string `json:"reason,omitempty"`
}

SessionEndedData carries session end information.

type SessionStartedData 

type SessionStartedData struct {
	SessionID string `json:"session_id"`
	Model     string `json:"model,omitempty"`
}

SessionStartedData carries session start metadata.

type State 

type State string

State represents the top-level agent state. 

const (
	StateInitialized State = "initialized"
	StateActive      State = "active"
	StateIdle        State = "idle"
	StateExited      State = "exited"
)

type StateChangeData 

type StateChangeData struct {
	State    State    `json:"state"`
	SubState SubState `json:"sub_state,omitempty"`
}

StateChangeData carries state transition information.

type SubState 

type SubState string

SubState represents the sub-state within Active. 

const (
	SubStateNone                 SubState = ""
	SubStateThinking             SubState = "thinking"
	SubStateToolUse              SubState = "tool_use"
	SubStateWaitingForPermission SubState = "waiting_for_permission"
	SubStateCompacting           SubState = "compacting"
)

type ToolCompletedData 

type ToolCompletedData struct {
	ToolName   string `json:"tool_name"`
	CallID     string `json:"call_id,omitempty"`
	DurationMs int64  `json:"duration_ms,omitempty"`
	Success    bool   `json:"success"`
}

ToolCompletedData carries tool invocation completion info.

type ToolStartedData 

type ToolStartedData struct {
	ToolName string `json:"tool_name"`
	CallID   string `json:"call_id,omitempty"`
}

ToolStartedData carries tool invocation start info.

type TransitionEvent 

type TransitionEvent string

TransitionEvent represents events that trigger state transitions. 

const (
	TransitionSessionStarted      TransitionEvent = "session_started"
	TransitionToolStarted         TransitionEvent = "tool_started"
	TransitionToolCompleted       TransitionEvent = "tool_completed"
	TransitionApprovalRequested   TransitionEvent = "approval_requested"
	TransitionPermissionGranted   TransitionEvent = "permission_granted"
	TransitionPermissionDenied    TransitionEvent = "permission_denied"
	TransitionCompactionStarted   TransitionEvent = "compaction_started"
	TransitionCompactionCompleted TransitionEvent = "compaction_completed"
	TransitionIdleTimeout         TransitionEvent = "idle_timeout"
	TransitionActivity            TransitionEvent = "activity"
	TransitionSessionEnded        TransitionEvent = "session_ended"
	TransitionProcessExit         TransitionEvent = "process_exit"
)

type TurnCompletedData 

type TurnCompletedData struct {
	TurnID       string  `json:"turn_id,omitempty"`
	InputTokens  int64   `json:"input_tokens"`
	OutputTokens int64   `json:"output_tokens"`
	CachedTokens int64   `json:"cached_tokens,omitempty"`
	CostUSD      float64 `json:"cost_usd,omitempty"`
}

TurnCompletedData carries turn completion metrics.

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.