Documentation
¶
Overview ¶
Package audit provides durable, structured logging of agent and tool events (commands, tool calls, LLM requests/responses, errors) for debugging and compliance.
It solves the problem of having a single, consistent audit trail: events are written as NDJSON to rotating files (~/.genie/{agent}.{date}.ndjson) or a configured path. Activity reports and downstream analytics can read these files. Without this package, there would be no unified record of what the agent did and which tools were invoked.
Index ¶
- func AgentNameFromContext(ctx context.Context) string
- func DefaultAuditPath(agentName string) string
- func DefaultAuditPathForDate(agentName string, t time.Time) string
- func WithAgentName(ctx context.Context, name string) context.Context
- type Auditor
- type Event
- type EventType
- type FileAuditor
- type LogRequest
- type LookupRequest
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AgentNameFromContext ¶
AgentNameFromContext extracts the agent name previously set via WithAgentName. Returns "" if not set.
func DefaultAuditPath ¶
DefaultAuditPath returns the default audit log path for the named agent for the current date. See DefaultAuditPathForDate for the format and semantics.
func DefaultAuditPathForDate ¶
DefaultAuditPathForDate returns the default audit log path for the named agent for the given date in the format ~/.genie/{agent_name}.<yyyy_mm_dd>.ndjson. Agent name is sanitized for filenames. Creates ~/.genie if missing. If home cannot be determined, uses workingDir. Empty agentName falls back to "genie". This is the single source of truth for the path format documented on config.AgentName.
Types ¶
type Auditor ¶
type Auditor interface {
Log(ctx context.Context, req LogRequest)
Recent(ctx context.Context, req LookupRequest) ([]Event, error)
Close() error
}
Auditor defines the interface for audit logging and reading recent events.
type Event ¶
type Event struct {
EventType string `json:"event_type"`
Actor string `json:"actor"`
Action string `json:"action"`
Timestamp time.Time `json:"timestamp"`
Metadata map[string]interface{} `json:"metadata,omitempty"`
}
Event represents a single parsed audit log entry (read path). It mirrors the structure written by Log (event_type, actor, action, timestamp, metadata).
type EventType ¶
type EventType string
EventType represents the type of audit event.
const ( // EventConnection is logged when a client connects. EventConnection EventType = "connection" // EventDisconnection is logged when a client disconnects. EventDisconnection EventType = "disconnection" // EventCommand is logged when a command is executed. EventCommand EventType = "command" // EventError is logged when an error occurs. EventError EventType = "error" // EventLLMRequest is logged when an LLM call starts. EventLLMRequest EventType = "llm_request" // EventLLMResponse is logged when an LLM call completes. EventLLMResponse EventType = "llm_response" // EventClassification is logged when the front desk classifies a request. EventClassification EventType = "classification" // EventToolCall is logged when a tool is invoked. EventToolCall EventType = "tool_call" // EventConversation is logged for a complete Q&A turn. EventConversation EventType = "conversation" // EventMemoryAccess is logged when memory is read, written, or deleted. EventMemoryAccess EventType = "memory_access" // EventSecretAccess is logged when a secret is looked up (Manager or keyring). // Only the secret name/key is recorded; the value is never logged. EventSecretAccess EventType = "secret_access" )
type FileAuditor ¶
type FileAuditor struct {
// contains filtered or unexported fields
}
FileAuditor implements Auditor and writes structured JSON logs to a file. It supports fixed path (single file) or date-rotating path (~/.genie/{agent}.<date>.ndjson).
func NewFixedPathAuditor ¶
func NewFixedPathAuditor(path string) (*FileAuditor, error)
NewFixedPathAuditor creates an auditor that writes to the given path (single file). Use for tests or when a custom audit path is configured. The file is created on first Log.
func NewRotatingFileAuditor ¶
func NewRotatingFileAuditor(agentName string) (*FileAuditor, error)
NewRotatingFileAuditor creates an auditor that writes to the default path for the current date (~/.genie/{agent_name}.<yyyy_mm_dd>.ndjson). On each Log call the path is resolved for "today" (UTC); when the date changes (e.g. after 24h uptime), the next log goes to the new day's file. Logs are always written to the correct date's file and serialized so lines are not interleaved.
func (*FileAuditor) Close ¶
func (a *FileAuditor) Close() error
Close closes the current audit log file. Safe to call multiple times.
func (*FileAuditor) Log ¶
func (a *FileAuditor) Log(ctx context.Context, req LogRequest)
Log records an audit event with structured fields. In rotating mode, resolves the path for the current date (UTC) so logs always go to the correct day's file. Metadata values are PII-redacted before writing.
func (*FileAuditor) Recent ¶
func (a *FileAuditor) Recent(ctx context.Context, req LookupRequest) ([]Event, error)
Recent reads audit log files for the agent from req.Since to now (UTC), parsing each NDJSON line with msg "audit_event" and returning events in chronological order. Uses req.AgentName when set; otherwise the FileAuditor's agent name. Without this method, activity report and other features could not obtain recent activities from the file audit trail.
type LogRequest ¶
LogRequest contains all fields needed to record an audit event. This follows the mandatory 2-parameter method pattern (ctx + request struct).
type LookupRequest ¶
LookupRequest contains parameters for reading recent audit events. Used by Recent to scope which agent and time window to read.
Source Files
Directories