Documentation
¶
Overview ¶
Package lifecycle is the Stage-1 namespace for session lifecycle, limits, timeouts, and sleep-time operations. After Stage 2 the implementation lives here and the engine root re-exports the public API. See ../REFACTOR_PLAN.md.
Note: engine.go (the Engine type itself) stays in the root engine package as the coordinator — it is NOT re-exported here. This cluster covers the supporting lifecycle infrastructure only.
Index ¶
- func ParseAndApplyMemoryOps(bridge *memory.YaadBridge, response string)
- func RemainingTime(ctx context.Context) string
- func TimeoutMessage(elapsed time.Duration) string
- func WithTimeout(ctx context.Context, cfg TimeoutConfig) (context.Context, context.CancelFunc)
- type CostEntry
- type CostTrackerInterface
- type EvolvingMemoryAdapter
- type EvolvingMemoryInterface
- type LimitTracker
- type SafetyLimits
- type SessionLifecycle
- type SessionOutcome
- type SkillDistillerAdapter
- type SkillStoreInterface
- type TimeoutConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseAndApplyMemoryOps ¶
func ParseAndApplyMemoryOps(bridge *memory.YaadBridge, response string)
ParseAndApplyMemoryOps parses the LLM's JSON response and applies memory operations via yaad.
func RemainingTime ¶
RemainingTime returns a formatted remaining-time string derived from the context deadline set by WithTimeout. If no deadline is set it returns an empty string.
func TimeoutMessage ¶
TimeoutMessage returns a user-friendly message when the time budget is exhausted.
func WithTimeout ¶
func WithTimeout(ctx context.Context, cfg TimeoutConfig) (context.Context, context.CancelFunc)
WithTimeout wraps a context with the total timeout and stores the deadline so that RemainingTime can report it.
Types ¶
type CostEntry ¶
type CostEntry struct {
SessionID string
TaskGoal string
TotalCost float64
Duration time.Duration
Success bool
Timestamp time.Time
}
CostEntry represents a single cost data point recorded at session end.
type CostTrackerInterface ¶
CostTrackerInterface abstracts cost recording and querying.
type EvolvingMemoryAdapter ¶
type EvolvingMemoryAdapter struct {
EM *memory.EvolvingMemory
}
EvolvingMemoryAdapter bridges memory.EvolvingMemory to the EvolvingMemoryInterface.
func (*EvolvingMemoryAdapter) Format ¶
func (a *EvolvingMemoryAdapter) Format() string
func (*EvolvingMemoryAdapter) Learn ¶
func (a *EvolvingMemoryAdapter) Learn(pattern, lesson string) error
func (*EvolvingMemoryAdapter) Retrieve ¶
func (a *EvolvingMemoryAdapter) Retrieve(query string) []string
type EvolvingMemoryInterface ¶
type EvolvingMemoryInterface interface {
Learn(pattern, lesson string) error
Retrieve(query string) []string
Format() string
}
EvolvingMemoryInterface abstracts guideline retrieval and learning so the lifecycle can be tested without real storage.
type LimitTracker ¶
type LimitTracker struct {
// contains filtered or unexported fields
}
LimitTracker tracks usage against limits.
func NewLimitTracker ¶
func NewLimitTracker(limits SafetyLimits) *LimitTracker
NewLimitTracker creates a LimitTracker with the given limits.
func (*LimitTracker) IsExceeded ¶
func (lt *LimitTracker) IsExceeded() (bool, string)
IsExceeded returns true and a human-readable reason when any limit is breached.
func (*LimitTracker) RecordCost ¶
func (lt *LimitTracker) RecordCost(usd float64)
RecordCost adds to the running cost total.
func (*LimitTracker) RecordTokens ¶
func (lt *LimitTracker) RecordTokens(n int)
RecordTokens adds output tokens to the running total.
func (*LimitTracker) RecordToolCall ¶
func (lt *LimitTracker) RecordToolCall(toolName string)
RecordToolCall records a tool invocation. Tools named "Bash" or "bash" also increment the bash command counter; "Write" or "Edit" increment file writes.
func (*LimitTracker) RecordTurn ¶
func (lt *LimitTracker) RecordTurn()
RecordTurn increments the turn counter.
func (*LimitTracker) Summary ¶
func (lt *LimitTracker) Summary() string
Summary returns a one-line summary of usage vs limits.
type SafetyLimits ¶
type SafetyLimits struct {
MaxToolCalls int // max total tool invocations (default: 200)
MaxFileWrites int // max files created/modified (default: 50)
MaxBashCommands int // max bash executions (default: 100)
MaxCostUSD float64 // max spend (default: from MaxBudgetUSD)
MaxTurns int // max LLM turns (default: from MaxTurns)
MaxOutputTokens int // max total output tokens (default: 500K)
}
SafetyLimits caps what the agent can do in a single session.
func DefaultLimits ¶
func DefaultLimits() SafetyLimits
DefaultLimits returns conservative safety limits for normal interactive use.
func ResearchLimits ¶
func ResearchLimits() SafetyLimits
ResearchLimits returns strict per-iteration limits suitable for research tasks.
func VibeLimits ¶
func VibeLimits() SafetyLimits
VibeLimits returns more permissive limits for autonomous/vibe mode.
type SessionLifecycle ¶
type SessionLifecycle struct {
Memory EvolvingMemoryInterface
SkillStore SkillStoreInterface
CostTracker CostTrackerInterface
}
SessionLifecycle manages the start and end of agent sessions, implementing the self-improvement loop that makes hawk better over time.
Research basis: - Reflexion (NeurIPS 2023): 91% HumanEval via episodic memory of reflections - ExpeL (AAAI 2024): extract insights from task experiences - Voyager: 15.3x faster with accumulated skill library - DSPy (Stanford): 25-65% improvement via curated few-shot examples
The closed loop: SESSION START:
- Retrieve relevant EvolvingMemory guidelines
- Inject few-shot examples from prior successes
- Load yaad context (conventions, active tasks, stale warnings)
SESSION END:
- Generate LLM reflection ("what worked, what failed, why")
- Extract guidelines via EvolvingMemory.Learn()
- Distill successful approaches into skills
- Record cost/performance metrics
- Trigger yaad consolidation
func (*SessionLifecycle) OnSessionEnd ¶
func (l *SessionLifecycle) OnSessionEnd(_ context.Context, session interface{}, outcome SessionOutcome) error
OnSessionEnd performs post-session learning.
func (*SessionLifecycle) OnSessionStart ¶
func (l *SessionLifecycle) OnSessionStart(_ context.Context, initialPrompt string) string
OnSessionStart prepares context for a new session. Returns context to inject into the system prompt.
type SessionOutcome ¶
type SessionOutcome struct {
Success bool
TaskGoal string
FilesChanged []string
ToolsUsed []string
TotalCost float64
Duration time.Duration
UserFeedback string // empty if none
}
SessionOutcome captures the results of a completed session.
type SkillDistillerAdapter ¶
type SkillDistillerAdapter struct {
SD *memory.SkillDistiller
}
SkillDistillerAdapter bridges memory.SkillDistiller to SkillStoreInterface. Skill distillation builds a prompt for LLM extraction — the actual distilled skills are stored as files in hawk-skills/.
func (*SkillDistillerAdapter) Distill ¶
func (a *SkillDistillerAdapter) Distill(goal string, steps []string, outcome string) error
func (*SkillDistillerAdapter) Retrieve ¶
func (a *SkillDistillerAdapter) Retrieve(_ string) []string
type SkillStoreInterface ¶
type SkillStoreInterface interface {
Distill(goal string, steps []string, outcome string) error
Retrieve(query string) []string
}
SkillStoreInterface abstracts skill distillation and retrieval.
type TimeoutConfig ¶
type TimeoutConfig struct {
Total time.Duration // total time for the entire operation
PerTurn time.Duration // max time per LLM turn (default: 60s)
PerTool time.Duration // max time per tool execution (default: 120s)
Countdown bool // show remaining time in output
}
TimeoutConfig controls operation time budgets.
func DefaultTimeoutConfig ¶
func DefaultTimeoutConfig() TimeoutConfig
DefaultTimeoutConfig returns a TimeoutConfig with sensible per-turn and per-tool defaults. Total is left at zero (no overall deadline) so the caller can set it.
Source Files