nudge

func EmitBillingWarning ¶

func EmitBillingWarning(logFile, sessionID string, count, tokens, threshold int) string

EmitBillingWarning builds a one-shot warning when token usage crosses the billing_token_warn threshold.

Parameters:

• logFile: absolute path to the log file
• sessionID: session identifier
• count: current prompt count
• tokens: token usage count
• threshold: billing token warning threshold

Returns:

• string: formatted nudge box, or empty string if silenced or already fired

func EmitCheckpoint ¶

func EmitCheckpoint(logFile, sessionID string, count, tokens, pct, windowSize int) string

EmitCheckpoint builds the standard checkpoint box with optional token usage.

Parameters:

• logFile: absolute path to the log file
• sessionID: session identifier
• count: current prompt count
• tokens: token usage count
• pct: context window usage percentage
• windowSize: total context window size

Returns:

• string: formatted nudge box, or empty string if silenced

func EmitNudge ¶

func EmitNudge(
	cmd *cobra.Command,
	content, relayPrefix, boxTitle,
	hookName, variant, relayMessage, sessionID string,
	vars map[string]any,
	markerPath string,
)

EmitNudge is the standard hook tail: print nudge box, send nudge+relay notifications, and touch the throttle marker.

Parameters:

• cmd: Cobra command for output
• content: nudge box content (from LoadMessage)
• relayPrefix: relay prefix text (e.g., "check-backup-age")
• boxTitle: nudge box title
• hookName: hook name for notifications
• variant: hook variant for template ref
• relayMessage: human-readable relay suffix
• sessionID: current session identifier
• vars: template variables for the template ref (may be nil)
• markerPath: throttle file to touch (empty string skips)

func EmitWindowWarning ¶

func EmitWindowWarning(logFile, sessionID string, count, tokens, pct int) string

EmitWindowWarning builds an independent context window warning (>80%).

Parameters:

• logFile: absolute path to the log file
• sessionID: session identifier
• count: current prompt count
• tokens: token usage count
• pct: context window usage percentage

Returns:

• string: formatted nudge box, or empty string if silenced

func LoadAndEmit ¶

func LoadAndEmit(
	cmd *cobra.Command,
	hookName, variant string,
	vars map[string]any,
	fallback,
	relayPrefix, boxTitle, relayMessage, sessionID, markerPath string,
)

LoadAndEmit loads a hook message template and, if non-empty, emits the standard nudge box + relay notification + throttle marker sequence.

Parameters:

• cmd: Cobra command for output
• hookName: hook name for message lookup and notifications
• variant: hook variant for message lookup and template ref
• vars: template variables (may be nil)
• fallback: fallback text if no template is found
• relayPrefix: relay prefix text
• boxTitle: nudge box title
• relayMessage: human-readable relay suffix
• sessionID: current session identifier
• markerPath: throttle file to touch (empty string skips)

func NudgeAndRelay ¶

func NudgeAndRelay(message, sessionID string, ref *notify.TemplateRef)

NudgeAndRelay sends both a nudge and a relay notification, then appends the relay event to the local event log. Used by hooks that emit both notification types with the same message.

Parameters:

• message: human-readable event description
• sessionID: current session identifier
• ref: template reference for filtering/aggregation (may be nil)

func Pause ¶

func Pause(sessionID string)

Pause creates the session pause marker. Exported for use by the top-level ctx pause command.

Parameters:

• sessionID: Session identifier

func PauseMarkerPath ¶

func PauseMarkerPath(sessionID string) string

PauseMarkerPath returns the path to the session pause marker file.

Parameters:

• sessionID: Session identifier

Returns:

• string: Absolute path to the pause marker file

func Paused ¶

func Paused(sessionID string) int

Paused checks if the session is paused. If paused, increments the turn counter and returns the current count. Returns 0 if not paused.

Parameters:

• sessionID: Session identifier

Returns:

• int: Turn count if paused, 0 if not paused

func PausedMessage ¶

func PausedMessage(turns int) string

PausedMessage returns the appropriate pause indicator for the given turn count, or empty string if not paused (turns == 0).

Parameters:

• turns: Number of paused turns

Returns:

• string: Pause message, or empty string

func Relay ¶

func Relay(message, sessionID string, ref *notify.TemplateRef)

Relay sends a relay notification and appends the same event to the local event log. This is the standard two-sink pattern used by most hooks after emitting output.

Parameters:

• message: human-readable event description
• sessionID: current session identifier
• ref: template reference for filtering/aggregation (may be nil)

func Resume ¶

func Resume(sessionID string)

Resume removes the session pause marker. Exported for use by the top-level ctx resume command. No-op if not paused.

Parameters:

• sessionID: Session identifier

func TokenUsageLine ¶

func TokenUsageLine(tokens, pct, windowSize int) string

TokenUsageLine formats a context window usage line for display. Shows an icon (normal or warning), token count, percentage, and window size.

Parameters:

• tokens: number of tokens used
• pct: percentage of the context window used
• windowSize: total context window size

Returns:

• string: formatted usage line (e.g., "⏱ Context window: ~12k tokens (~60% of 200k)")