Documentation
¶
Overview ¶
Package session contains the public session state model for agentwatch.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComputeContextUtilization ¶
ComputeContextUtilization returns ContextTokens/MaxContextTokens as a fraction in [0,1], or 0 if MaxContextTokens is zero.
Types ¶
type Activity ¶
type Activity string
Activity represents what an agent session is currently doing.
const ( // ActivityIdle indicates the session is running but not actively processing. ActivityIdle Activity = "idle" // ActivityWorking indicates the session is actively processing a request. ActivityWorking Activity = "working" // ActivityWaiting indicates the session is waiting for user input. ActivityWaiting Activity = "waiting" // ActivityTerminal indicates the session has ended. ActivityTerminal Activity = "terminal" )
func (*Activity) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler. It accepts any string value to remain forward-compatible, but unknown values round-trip as-is.
type LifecycleEvent ¶
type LifecycleEvent struct {
Type LifecycleEventType `json:"type"`
SessionID string `json:"sessionId"`
Source string `json:"source"`
From LifecycleState `json:"from"`
To LifecycleState `json:"to"`
At time.Time `json:"at"`
Reason string `json:"reason,omitempty"`
}
LifecycleEvent records a single state transition for a session.
type LifecycleEventType ¶
type LifecycleEventType string
LifecycleEventType names the kind of transition that occurred.
const ( // EventDiscovered fires when a session is first tracked. EventDiscovered LifecycleEventType = "discovered" // EventUpdated fires when new data arrives for an active session. EventUpdated LifecycleEventType = "updated" // EventResumed fires when a terminal session receives new data. EventResumed LifecycleEventType = "resumed" // EventTerminal fires when a session transitions to terminal state. EventTerminal LifecycleEventType = "terminal" // EventStale fires when no data is received past the stale threshold. EventStale LifecycleEventType = "stale" // EventRemoved fires when a terminal session's retention window expires // and it is removed from the store. EventRemoved LifecycleEventType = "removed" )
type LifecycleState ¶
type LifecycleState string
LifecycleState is the durable state of a session — either active or terminal. "Resumed" is an event, not a durable state.
const ( // LifecycleActive means the session is being tracked and may receive updates. LifecycleActive LifecycleState = "active" // LifecycleTerminal means the session has ended and will be retained briefly // before removal. LifecycleTerminal LifecycleState = "terminal" )
type Policy ¶
type Policy struct {
// RedactWorkingDir replaces WorkingDir with an empty string.
// WorkingDir is a local filesystem path and may reveal project names or
// directory layouts that the caller does not want to expose.
RedactWorkingDir bool
// RedactBranch replaces Branch with an empty string.
// Branch names often encode feature names, ticket IDs, or user handles.
RedactBranch bool
// RedactModel replaces Model with an empty string.
// Model names may reveal subscription tier or internal tooling choices.
RedactModel bool
// RedactSessionID replaces ID and Slug with empty strings, and also
// clears ID and ParentID on every Subagent. Session identifiers can
// correlate activity across requests or log streams.
RedactSessionID bool
// RedactSource replaces Source with an empty string.
// Source names identify which agent toolchain is in use, which some
// callers may consider sensitive.
RedactSource bool
}
Policy controls which SessionState fields are redacted before external exposure. A zero-value Policy is a passthrough — nothing is redacted.
All fields default to false (no redaction). Callers opt in to each redaction independently so that consumers can choose the sensitivity level appropriate for their deployment.
Design note: every exported field of SessionState and SubagentState must be reviewed and listed in the TestPrivacyFilter_FieldCoverage sentinel test. If you add a field to either struct, add it to that set and assess whether it belongs under an existing or new Policy flag.
func (Policy) Apply ¶
func (p Policy) Apply(s SessionState) SessionState
Apply returns a deep copy of s with sensitive fields redacted according to the policy. The original state is never mutated.
type SessionState ¶
type SessionState struct {
ID string `json:"id"`
Source string `json:"source"`
Slug string `json:"slug,omitempty"`
Activity Activity `json:"activity"`
Lifecycle LifecycleState `json:"lifecycle"`
ContextTokens int `json:"contextTokens"`
OutputTokens int `json:"outputTokens,omitempty"`
TokenEstimated bool `json:"tokenEstimated"`
MaxContextTokens int `json:"maxContextTokens"`
ContextUtilization float64 `json:"contextUtilization"`
Model string `json:"model"`
WorkingDir string `json:"workingDir"`
Branch string `json:"branch,omitempty"`
CurrentTool string `json:"currentTool,omitempty"`
MessageCount int `json:"messageCount"`
ToolCallCount int `json:"toolCallCount"`
CompactionCount int `json:"compactionCount"`
StartedAt time.Time `json:"startedAt"`
LastActivityAt time.Time `json:"lastActivityAt"`
LastDataReceivedAt time.Time `json:"lastDataReceivedAt"`
CompletedAt *time.Time `json:"completedAt,omitempty"`
Subagents []SubagentState `json:"subagents,omitempty"`
}
SessionState is the public snapshot of a monitored agent session.
func (SessionState) Clone ¶
func (s SessionState) Clone() SessionState
Clone returns a deep copy of s. Callers may mutate the copy without affecting the original.
type SubagentState ¶
type SubagentState struct {
ID string `json:"id"`
ParentID string `json:"parentId,omitempty"`
Slug string `json:"slug,omitempty"`
Activity Activity `json:"activity"`
CurrentTool string `json:"currentTool,omitempty"`
StartedAt time.Time `json:"startedAt"`
LastActivityAt time.Time `json:"lastActivityAt"`
Model string `json:"model,omitempty"`
ContextTokens int `json:"contextTokens"`
OutputTokens int `json:"outputTokens,omitempty"`
MessageCount int `json:"messageCount"`
ToolCallCount int `json:"toolCallCount"`
CompletedAt time.Time `json:"completedAt,omitempty"`
}
SubagentState tracks a nested agent spawned within a parent session.
Source Files