hooks

type HookMeta struct {
	SessionID string
	UserID    string
	AgentID   string
	Channel   string
}

type HookPlugin interface {
	Name() string
	Priority() int // lower = runs first; ties broken by Name() lexicographic
}

type HookPoint string

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

type MemoryOp string

type PostAgentCallContext struct {
	HookMeta
	Duration time.Duration
	Error    error
}

type PostAgentCallHook interface {
	Name() string
	Priority() int
	OnPostAgentCall(ctx context.Context, hctx *PostAgentCallContext)
}

type PostLLMCallContext struct {
	HookMeta
	Model            string
	Provider         string // provider display name (may be empty)
	API              string // provider API key (e.g. "anthropic", "openai")
	BaseURL          string // provider endpoint URL
	Usage            ai.Usage
	StopReason       ai.StopReason
	Duration         time.Duration
	TimeToFirstToken time.Duration // zero if no streaming or first token not observed
	Error            error
}

type PostLLMCallHook interface {
	Name() string
	Priority() int
	OnPostLLMCall(ctx context.Context, hctx *PostLLMCallContext)
}

type PostMemoryCallContext struct {
	HookMeta
	Op        MemoryOp
	SessionID string // memory session ID
	Duration  time.Duration
	Error     error
	// Operation-specific fields (zero values for irrelevant ops).
	MessageCount int // Append: number of messages; Assemble: returned count
	TokenCount   int // Assemble: total tokens; Stats: total tokens; Compact: tokens after
	TokenDelta   int // Compact: tokens saved (negative = reduction)
	SummaryCount int // Compact: summaries created; Stats: total summaries
	ResultCount  int // Search: number of results
	// Detail contains a human-readable dump of the operation's content.
	// Only populated when verbose tracing is enabled. Empty in normal mode.
	// Append: message roles/previews. Assemble: returned messages.
	// Search: query + results. Profile: content. Compact: result breakdown.
	Detail string
}

type PostMemoryCallHook interface {
	Name() string
	Priority() int
	OnPostMemoryCall(ctx context.Context, hctx *PostMemoryCallContext)
}

type PostToolCallContext struct {
	HookMeta
	ToolName   string
	ToolCallID string
	Arguments  map[string]any
	Result     string
	IsError    bool
	Duration   time.Duration
}

type PostToolCallHook interface {
	Name() string
	Priority() int
	OnPostToolCall(ctx context.Context, hctx *PostToolCallContext)
}

type PreAgentCallContext struct {
	HookMeta
	MessageLen int    // length of the user message text
	Channel    string // channel the chat originated from (e.g. "cli", "telegram")
}

type PreAgentCallHook interface {
	Name() string
	Priority() int
	OnPreAgentCall(ctx context.Context, hctx *PreAgentCallContext)
}

type PreLLMCallContext struct {
	HookMeta
	Model           string
	System          string
	ToolDefinitions []ai.ToolDefinition
	MessageCount    int // number of messages (avoid copying full history)

	// Model/request metadata for tracing.
	API         string   // provider API key (e.g. "anthropic", "openai")
	Provider    string   // provider display name
	BaseURL     string   // provider endpoint URL
	MaxTokens   *int     // nil = not set
	Temperature *float64 // nil = not set
}

type PreLLMCallHook interface {
	Name() string
	Priority() int
	OnPreLLMCall(ctx context.Context, hctx *PreLLMCallContext) (PreLLMCallResult, error)
}

type PreLLMCallResult struct {
	System          *string             // non-nil = override system prompt
	ToolDefinitions []ai.ToolDefinition // non-nil = override tool definitions
	Model           *string             // non-nil = override model name
	Context         context.Context     // non-nil = enriched context for provider call (e.g. with trace span)
}

type PreMemoryCallContext struct {
	HookMeta
	Op        MemoryOp
	SessionID string // memory session ID, empty for global/user memory ops
}

type PreMemoryCallHook interface {
	Name() string
	Priority() int
	OnPreMemoryCall(ctx context.Context, hctx *PreMemoryCallContext) (PreMemoryCallResult, error)
}

type PreMemoryCallResult struct {
	Context context.Context // non-nil = enriched context for the memory operation
}

type PreToolCallContext struct {
	HookMeta
	ToolName   string
	ToolCallID string
	Arguments  map[string]any // read by hook; rewrite via result
}

type PreToolCallHook interface {
	Name() string
	Priority() int
	OnPreToolCall(ctx context.Context, hctx *PreToolCallContext) (PreToolCallResult, error)
}

type PreToolCallResult struct {
	Arguments    map[string]any  // non-nil = rewritten args for next hook / execution
	Block        bool            // true = skip tool execution
	BlockMessage string          // synthetic result text when blocked
	Context      context.Context // non-nil = enriched context for tool execution (e.g. with trace span)
}