streamevent

Documentation

Overview

Package streamevent emits diagnostic JSON-line events on stdout so observers (the inference-gateway/infer-action runner, log scrapers, human eyeballs in CI) can see internal agent lifecycle moments that are otherwise silent - system reminder injections, conversation compaction triggers, and similar checkpoints.

Events are HIDDEN BY DEFAULT and only emitted when the global logger is configured at debug level (via `--verbose`, `logging.debug=true`, or env var `INFER_LOGGING_DEBUG=true`). This keeps normal `infer agent` runs quiet on stdout while letting operators turn on the firehose when they need to diagnose.

Two shapes are emitted:

• EmitDebugMessage mirrors a real conversation message (`role`, `content`) with `hidden: true` and a `kind` discriminator. Use this when surfacing an internally-injected message the LLM received - e.g. a hidden user-role system-reminder turn.

• EmitDebugEvent emits an operational lifecycle event keyed by `type`, not `role`. Use this for things that aren't conversation turns at all - e.g. "auto-compaction crossed the token threshold".

Index

• func EmitDebugEvent(eventType string, fields map[string]any)
• func EmitDebugMessage(role, content, kind string, extra map[string]any)
• func SetDebugEnabledForTest(enabled bool) func()
• func SetWriter(w io.Writer) func()

Functions

func EmitDebugEvent

func EmitDebugEvent(eventType string, fields map[string]any)

EmitDebugEvent writes a JSON-line describing an operational lifecycle event keyed by `type`. Used for things that are NOT conversation messages (e.g. compaction triggers, token-threshold crossings).

No-op unless debug is enabled (see package docs).

func EmitDebugMessage

func EmitDebugMessage(role, content, kind string, extra map[string]any)

EmitDebugMessage writes a JSON-line that mirrors the shape of a normal conversation message but flagged `hidden: true` and tagged with a `kind` discriminator so observers can distinguish it from real conversation turns. Used to surface internally-injected messages (e.g. the hidden user-role system-reminder appended every N turns) that the user would not otherwise see.

No-op unless debug is enabled (see package docs).

func SetDebugEnabledForTest

func SetDebugEnabledForTest(enabled bool) func()

SetDebugEnabledForTest forces the debug gate to a specific value, bypassing the global-logger probe. Returns a restore function. Test-only.

func SetWriter

func SetWriter(w io.Writer) func()

SetWriter overrides the destination io.Writer for emitted events and returns a restore function. Used by tests; production callers should not touch it.