Documentation
¶
Overview ¶
Package agent_audit defines the facts-only per-call audit events the agent emits for every model call and tool execution, and the process-wide sink that records them. Events carry digests and metadata only — never prompt text, response text, message content, or raw tool arguments — so a host can reconstruct what the agent did without storing what it said.
The package is deliberately dependency-free (standard library only) so both the agent package and the provider package can import it without a cycle: the agent owns the sink and the call context, the provider emits the model call, and neither imports the other for auditing.
Index ¶
- Constants
- func Digest(b []byte) (string, int)
- func EmitCall(ctx context.Context, ev CallEvent)
- func EmitTool(ctx context.Context, ev ToolEvent)
- func EndpointHost(endpoint string) string
- func ResolveTrigger(ctx context.Context, lastMessageRole string) string
- func SetSink(s Sink)
- func WithCallContext(ctx context.Context, cc CallContext) context.Context
- type CallContext
- type CallEvent
- type Sink
- type ToolEvent
Constants ¶
const ( KindModelCall = "model_call" KindToolCall = "tool_call" )
Event kinds, written to the Kind field so a reader can discriminate a model call from a tool execution in a single JSONL stream.
const ( OutcomeOK = "ok" OutcomeError = "error" OutcomeFailover = "failover" )
Call outcomes.
const ( TriggerUserTurn = "user_turn" TriggerToolFollowUp = "tool_call_follow_up" TriggerSubagent = "subagent" )
Triggers describe what caused a model call.
Variables ¶
This section is empty.
Functions ¶
func EmitCall ¶
EmitCall records a model-call event. It fills the event's context-derived fields (chat id, session id), its trigger, and its timestamp, then forwards to the installed sink. Nil-safe: a no-op when no sink is installed.
func EmitTool ¶
EmitTool records a tool-execution event. It fills the context-derived fields and timestamp, then forwards to the installed sink. Nil-safe.
func EndpointHost ¶
EndpointHost returns the host (host:port) of an endpoint URL. When the endpoint does not parse as a URL it falls back to the substring before the first '/', so a path is never returned. Credentials (userinfo) are never returned either.
func ResolveTrigger ¶
ResolveTrigger derives the trigger for a model call. A subagent's calls are always subagent-triggered; otherwise a request whose last message is a tool result is a tool-call follow-up, and anything else is a user turn.
func SetSink ¶
func SetSink(s Sink)
SetSink installs the process-wide audit sink. Pass nil to remove it. The last installer wins, mirroring the process-global audit log the sink writes to; an agent that owns the sink clears it on shutdown.
func WithCallContext ¶
func WithCallContext(ctx context.Context, cc CallContext) context.Context
WithCallContext attaches audit metadata to ctx.
Types ¶
type CallContext ¶
CallContext is the per-call audit metadata the agent attaches to the context it hands the provider. It travels with the context rather than the process-wide sink so concurrent agents (subagents, multi-chat daemons) never clobber each other's session identity.
func CallContextFrom ¶
func CallContextFrom(ctx context.Context) (CallContext, bool)
CallContextFrom reads the audit metadata attached to ctx.
type CallEvent ¶
type CallEvent struct {
Time time.Time `json:"time"`
Kind string `json:"kind"`
ChatID string `json:"chat_id,omitempty"`
SessionID string `json:"session_id,omitempty"`
Provider string `json:"provider"`
Model string `json:"model"`
EndpointHost string `json:"endpoint_host,omitempty"`
RequestSHA256 string `json:"request_sha256,omitempty"`
RequestBytes int `json:"request_bytes"`
ResponseSHA256 string `json:"response_sha256,omitempty"`
ResponseBytes int `json:"response_bytes"`
PromptTokens int `json:"prompt_tokens"`
CompletionTokens int `json:"completion_tokens"`
Outcome string `json:"outcome"`
Trigger string `json:"trigger"`
Streaming bool `json:"streaming,omitempty"`
Failover bool `json:"failover,omitempty"`
}
CallEvent is one model call the agent made. It records the wire facts of the request and response (digests and byte counts), the token usage, the outcome, and the trigger. It never carries request or response content.
type Sink ¶
Sink records audit events. The agent installs one process-wide sink at startup; it fans events out to the local audit log and, when a host configures an audit endpoint, to that endpoint in batches.
func CurrentSink ¶
func CurrentSink() Sink
CurrentSink returns the installed sink, or nil when none is set.
type ToolEvent ¶
type ToolEvent struct {
Time time.Time `json:"time"`
Kind string `json:"kind"`
ChatID string `json:"chat_id,omitempty"`
SessionID string `json:"session_id,omitempty"`
Tool string `json:"tool"`
ArgsSHA256 string `json:"args_sha256,omitempty"`
ArgsBytes int `json:"args_bytes"`
Status string `json:"status"`
FilesTouched []string `json:"files_touched,omitempty"`
Trigger string `json:"trigger,omitempty"`
}
ToolEvent is one tool execution. It records the tool name, a digest of the arguments, the result status, and the file paths the call declared. It never carries the raw arguments or the tool output.
Source Files