Documentation
¶
Overview ¶
Package sessions defines cross-repo types for agent session state management.
Every multi-step coding-agent pipeline (localize → repair → validate) needs a shared vocabulary for session identity, pipeline phase, context snapshots, and cost accounting. Defining these types here — in the leaf contracts module — lets all engines and the orchestrator agree on a single schema without creating circular dependencies.
Evidence basis: CAT (arXiv 2512.22087) demonstrates that context management as a first-class concern improves long-horizon agent performance. ACON (arXiv 2510.00615) shows 26–54% token savings when phase-aware compression is applied. The Tokenomics study (arXiv 2601.14470) measured that code review alone consumes 59.4% of total tokens in multi-agent SE systems.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ContextSnapshot ¶
type ContextSnapshot struct {
SessionID SessionID `json:"session_id"`
Phase Phase `json:"phase"`
TokenCount int `json:"token_count"`
CompressedAt time.Time `json:"compressed_at"`
Summary string `json:"summary,omitempty"`
Anchors []string `json:"anchors,omitempty"`
}
ContextSnapshot is a point-in-time, compressed view of an agent's working memory. It is created by the tok CompactContext call and stored so that a new session can resume from a known good state without replaying history.
Anchors hold immutable facts (file paths, error messages, invariants) that must survive every compaction and must always be re-injected into context.
type CostAccumulator ¶
type CostAccumulator struct {
SessionID SessionID `json:"session_id"`
ByPhase map[Phase]PhaseUsage `json:"by_phase"`
TotalTokens int `json:"total_tokens"`
TotalCostUSD float64 `json:"total_cost_usd"`
}
CostAccumulator tracks token consumption and monetary cost across all pipeline phases within a session. It is the single source of truth for the cost-per-resolution metric exposed by hawk's ResolutionPipeline.
func NewCostAccumulator ¶
func NewCostAccumulator(id SessionID) *CostAccumulator
NewCostAccumulator returns a zero-value CostAccumulator for the given session.
func (*CostAccumulator) Add ¶
func (c *CostAccumulator) Add(phase Phase, inputTokens, outputTokens int, costUSD float64)
Add records input/output token usage and cost for a given phase.
func (*CostAccumulator) PhaseShare ¶
func (c *CostAccumulator) PhaseShare(phase Phase) float64
PhaseShare returns the fraction of total tokens attributed to the given phase. Returns 0 when no tokens have been recorded.
func (*CostAccumulator) String ¶
func (c *CostAccumulator) String() string
String returns a one-line summary suitable for log output.
type Phase ¶
type Phase string
Phase identifies the pipeline stage that generated a token-usage event. Engines tag their tok.Tracker events with the appropriate Phase so that hawk's orchestrator can build per-phase cost breakdowns and apply optimal compaction budgets for each stage.
const ( // PhaseLocalize is the file/symbol retrieval stage (Agentless Stage 1+2). PhaseLocalize Phase = "localize" // PhaseRepair is the patch-generation stage (Agentless Stage 2). PhaseRepair Phase = "repair" // PhaseValidate is the test-execution and patch-ranking stage (Agentless Stage 3). PhaseValidate Phase = "validate" // PhaseReview is the LLM-based code-review stage (sight/inspect). // The Tokenomics paper shows this phase dominates token usage (~59.4%). PhaseReview Phase = "review" // PhasePlanning is the task-decomposition stage (pre-execution). PhasePlanning Phase = "planning" // PhaseUnknown is the default zero value — used when phase attribution is unavailable. PhaseUnknown Phase = "" )
func ParsePhase
deprecated
ParsePhase parses a phase name string into a Phase constant. Returns PhaseUnknown for unrecognised values rather than an error, so callers that receive phase names from JSON/TOML do not need to handle errors.
Deprecated: ParsePhase fails open — misspelled or otherwise unknown phase names silently map to PhaseUnknown, which is indistinguishable from "phase attribution unavailable". Callers handling untrusted input should use ParsePhaseStrict, which reports unknown values as errors instead.
func ParsePhaseStrict ¶ added in v0.1.13
ParsePhaseStrict converts a phase name string into a Phase constant, reporting unknown values as errors instead of failing open to PhaseUnknown. Matching is exact, exactly like ParsePhase; the two accept the same set of valid names.
type PhaseUsage ¶
type PhaseUsage struct {
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
TotalTokens int `json:"total_tokens"`
CostUSD float64 `json:"cost_usd"`
}
PhaseUsage captures token and cost usage for a single pipeline phase.
type SessionID ¶
type SessionID string
SessionID is an opaque, globally unique identifier for a single agent session.
type ToolCallRecord ¶
type ToolCallRecord struct {
SessionID SessionID `json:"session_id"`
Phase Phase `json:"phase"`
ToolName string `json:"tool_name"`
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
DurationMs int64 `json:"duration_ms"`
Error string `json:"error,omitempty"`
Timestamp time.Time `json:"timestamp"`
}
ToolCallRecord captures a single tool invocation within a session, tagged with the pipeline phase in which it occurred. Accumulating these records lets hawk build a per-tool, per-phase cost profile that drives adaptive budget allocation in subsequent runs.
Source Files