toolinvocations

Documentation

Index

• Constants
• func RedactForLedger(s string, capBytes int) string
• type Event
• type Store
  • func New(pool *pgxpool.Pool) *Store
  • func (s *Store) Insert(ctx context.Context, e Event) error
  • func (s *Store) ListByConversation(ctx context.Context, conversationID string) ([]Event, error)

Constants

const (
	// ArgsRawCapBytes bounds the durable args_raw column (8 KiB). A larger ceiling
	// than the preview cap because tool argument JSON (scripts, write bodies) is
	// legitimately bulkier; still bounded so a pathological arg blob cannot bloat
	// the un-deletable ledger.
	ArgsRawCapBytes = 8 * 1024
	// ResultPreviewCapBytes bounds the durable result_preview column (2 KiB),
	// mirroring AURA_CONTEXT_PREVIEW_CAP_BYTES (the agent's tool-result preview cap)
	// so the ledger preview never exceeds the in-context preview the model saw.
	ResultPreviewCapBytes = 2 * 1024
)

WR-02: the append-only aura.tool_invocations ledger captures the VERBATIM tool argument JSON + result preview for forensics. A model can place a secret on a shell_exec/sandbox_exec command line (an inline `Authorization: Bearer ...`, an API key, a `password=...`). Migration 0011's triggers reject DELETE, so any captured secret is durable, append-only, and un-deletable (removed only by a conversation FK-cascade) while aura_app retains SELECT. RedactForLedger is the bounded, capped, redacted capture seam applied at the persistence boundary (toParams) BEFORE a value reaches the durable column, so no caller can write a raw secret into the ledger.

Posture: replace DB-invalid NUL bytes, cap the durable footprint, then redact over the capped string (so an over-cap secret tail is already truncated away, and the redactor scans a bounded input). The caps mirror the existing preview discipline: the result preview cap is AURA_CONTEXT_PREVIEW_CAP_BYTES=2048 (internal/agent), so result_preview keeps that ceiling here; args_raw gets a larger 8 KiB ceiling because a legitimate multi-tool argument JSON (a long shell script, a write payload) is bulkier than a result preview yet still bounded for the ledger.

const (
	EventStart = "start"
	EventEnd   = "end"
)

EventStart and EventEnd label append-only tool invocation lifecycle rows.

Functions

func RedactForLedger

func RedactForLedger(s string, capBytes int) string

RedactForLedger caps s to capBytes (UTF-8 boundary-safe) then redacts every known credential shape, returning the value safe to persist into the append-only ledger. An empty input returns empty (the column stays NULL upstream via the existing valid-flag). capBytes <= 0 means "no cap" (redact only).

Types

type Event

type Event struct {
	ID                string
	ConversationID    string
	RequestID         string
	ToolCallID        string
	ToolName          string
	Event             string
	Seq               int
	Timestamp         time.Time
	StartedAt         time.Time
	EndedAt           time.Time
	DurationMS        int64
	Arguments         string
	ArgsBytes         int
	Status            string
	Error             string
	ResultPreview     string
	PreviewBytes      int
	ResultBytes       int
	ResultTruncated   bool
	ResultSidecarPath string
	ExitCode          *int
	Meta              map[string]any
}

Event is one append-only fact in aura.tool_invocations. Start and end events are correlated by ConversationID + RequestID + ToolCallID.

type Store

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

Store is the append-only tool invocation ledger wrapper over sqlc.

func New

func New(pool *pgxpool.Pool) *Store

New builds a tool invocation store backed by the provided Postgres pool.

func (*Store) Insert

func (s *Store) Insert(ctx context.Context, e Event) error

Insert appends one tool invocation event to the ledger.

func (*Store) ListByConversation

func (s *Store) ListByConversation(ctx context.Context, conversationID string) ([]Event, error)

ListByConversation returns all tool invocation events for one conversation.