Middleware & Hooks

Chronos uses a hook-based middleware system to intercept execution events. Hooks run before and after model calls, tool calls, graph nodes, and session lifecycle events. Use them for logging, metrics, retries, rate limiting, cost tracking, and caching.

Hook Interface

Every hook implements the Hook interface:

type Hook interface {
    Before(ctx context.Context, evt *Event) error
    After(ctx context.Context, evt *Event) error
}

• Before: Called before the event executes. Return an error to abort the operation.
• After: Called after the event executes. Runs even when the operation fails.

Chain

Hooks are composed in a Chain (a slice of Hook). The chain runs Before in order and After in reverse (middleware unwinding pattern).

chain := hooks.Chain{hook1, hook2, hook3}
if err := chain.Before(ctx, evt); err != nil {
    return err  // hook1 or hook2 or hook3 aborted
}
// ... execute operation ...
chain.After(ctx, evt)  // hook3, hook2, hook1

Event Struct

Each hook receives an Event:

type Event struct {
    Type     EventType      // kind of event
    Name     string         // tool name, model name, or node ID
    Input    any            // request or input state
    Output   any            // response or output state
    Error    error          // error if operation failed
    Metadata map[string]any // extensible metadata
}

Event Types

Type	When Fired
tool_call.before	Before a tool is executed
tool_call.after	After a tool returns
model_call.before	Before an LLM chat request
model_call.after	After an LLM response
node.before	Before a graph node runs
node.after	After a graph node completes
context.overflow	When context limit is exceeded (before summarization)
context.summarize	After summarization completes
session.start	When a session chat begins
session.end	When a session chat ends

Adding Hooks

Attach hooks via the agent builder:

a, err := agent.New("my-agent", "My Agent").
    WithModel(provider).
    AddHook(loggingHook).
    AddHook(metricsHook).
    Build()

Built-in Hooks

LoggingHook

Records events to a slice for inspection or logging. Useful for debugging and audit trails.

loggingHook := &hooks.LoggingHook{}
a.AddHook(loggingHook)

// After execution
for _, evt := range loggingHook.Events {
    fmt.Printf("%s: %s\n", evt.Type, evt.Name)
}

RetryHook

Retries failed model calls with exponential backoff and jitter. The hook signals retry via event metadata; the caller (agent) must implement the actual retry loop.

retry := hooks.NewRetryHook(3)
retry.BaseDelay = 500 * time.Millisecond
retry.MaxDelay = 30 * time.Second
retry.RetryableError = func(err error) bool {
    return strings.Contains(err.Error(), "rate limit")
}
retry.OnRetry = func(attempt int, delay time.Duration) {
    log.Printf("Retry attempt %d after %v", attempt, delay)
}

a.AddHook(retry)

Field	Type	Description
MaxRetries	int	Maximum retry attempts (default 3)
BaseDelay	time.Duration	Initial delay (default 500ms)
MaxDelay	time.Duration	Cap on delay (default 30s)
RetryableError	func(error) bool	Classify errors; nil = retry all
OnRetry	func(int, time.Duration)	Callback before each retry
Retries	int	Total retries performed (observability)

When a retry is signaled, the hook sets evt.Metadata["retry"] = true, retry_attempt, and retry_delay.

RateLimitHook

Enforces per-provider rate limits using a token-bucket algorithm. Blocks on model_call.before when the limit would be exceeded (or returns an error if WaitOnLimit is false).

rl := hooks.NewRateLimitHook(60, 100000)  // 60 req/min, 100K tokens/min
rl.WaitOnLimit = true  // block until capacity available (default)

a.AddHook(rl)

Field	Type	Description
RequestsPerMinute	int	Max model calls per minute; 0 = unlimited
TokensPerMinute	int	Max prompt tokens per minute; 0 = unlimited
WaitOnLimit	bool	Block (true) or return error (false); default true

CostTracker

Tracks LLM API costs per session and globally. Enforces an optional budget by blocking model calls when the limit is exceeded.

tracker := hooks.NewCostTracker(nil)  // nil = use built-in price table
tracker.Budget = 10.0  // $10 max spend; 0 = unlimited

a.AddHook(tracker)

// After execution
global := tracker.GetGlobalCost()
sessionCost := tracker.GetSessionCost(sessionID)
fmt.Printf("Total: $%.4f, Session: $%.4f\n", global.TotalCost, sessionCost.TotalCost)

Field	Type	Description
Budget	float64	Max total spend (USD); 0 = unlimited

Built-in price table includes GPT-5.5, GPT-5, GPT-4o, o-series, Claude (Opus 4.8, Sonnet 5, Haiku 4.5, Fable 5), Gemini, and Mistral. Pass a custom map[string]ModelPrice to NewCostTracker to override. Prices track mid-2026 rates — override for current pricing.

CacheHook

Caches LLM responses for identical requests. Uses SHA-256 of the serialized request as the cache key. Skips streaming and tool-call responses.

cache := hooks.NewCacheHook(5 * time.Minute)
cache.MaxEntries = 1000  // LRU eviction when exceeded; 0 = unlimited

a.AddHook(cache)

hits, misses := cache.Stats()
fmt.Printf("Cache: %d hits, %d misses\n", hits, misses)

Field	Type	Description
TTL	time.Duration	How long entries remain valid (default 5 min)
MaxEntries	int	Max cache size; 0 = unlimited
Hits	int	Cache hits
Misses	int	Cache misses

MetricsHook

Tracks latency, token usage, and error rates for model and tool calls.

metrics := hooks.NewMetricsHook()
a.AddHook(metrics)

// Raw metrics
calls := metrics.GetMetrics()
for _, c := range calls {
    fmt.Printf("%s %s: %v\n", c.Type, c.Name, c.Duration)
}

// Aggregated summary
summary := metrics.GetSummary()
fmt.Printf("Model calls: %d, avg latency: %v, errors: %d\n",
    summary.TotalModelCalls, summary.AvgModelLatency, summary.TotalErrors)

MetricsSummary Field	Description
TotalModelCalls	Number of model calls
TotalToolCalls	Number of tool calls
TotalErrors	Calls that failed
TotalPromptTokens	Sum of prompt tokens
TotalCompTokens	Sum of completion tokens
AvgModelLatency	Average model call duration
AvgToolLatency	Average tool call duration
MaxModelLatency	Longest model call
MaxToolLatency	Longest tool call

Complete Example: Combining Hooks

package main

import (
    "context"
    "log"
    "os"
    "time"

    "github.com/spawn08/chronos/engine/hooks"
    "github.com/spawn08/chronos/engine/model"
    "github.com/spawn08/chronos/sdk/agent"
)

func main() {
    ctx := context.Background()

    provider := model.NewOpenAI(os.Getenv("OPENAI_API_KEY"))

    logging := &hooks.LoggingHook{}
    metrics := hooks.NewMetricsHook()
    cost := hooks.NewCostTracker(nil)
    cost.Budget = 5.0
    cache := hooks.NewCacheHook(10 * time.Minute)
    rl := hooks.NewRateLimitHook(30, 50000)

    a, err := agent.New("monitored-agent", "Monitored Agent").
        WithModel(provider).
        WithSystemPrompt("You are a helpful assistant.").
        AddHook(logging).
        AddHook(metrics).
        AddHook(cost).
        AddHook(cache).
        AddHook(rl).
        Build()
    if err != nil {
        log.Fatal(err)
    }

    resp, err := a.Chat(ctx, "What is 2 + 2?")
    if err != nil {
        log.Fatal(err)
    }
    log.Println(resp.Content)

    summary := metrics.GetSummary()
    log.Printf("Model calls: %d, latency: %v, cost: $%.4f",
        summary.TotalModelCalls, summary.AvgModelLatency, cost.GetGlobalCost().TotalCost)

    hits, misses := cache.Stats()
    log.Printf("Cache: %d hits, %d misses", hits, misses)
}