eventlog

package
v3.1.0-dev.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Durable continuation claims (#977).

agent_run_lock stops two daemons from *deciding* to continue a session at the same instant. It does not stop them from deciding one after the other, because the lock is released before the continuation turn runs — the turn executes asynchronously in the session's wake loop and that path has no turn-end hook to hold a lease across. So the second daemon acquires the lock cleanly, reads a tail that still looks interrupted (the first daemon's turn has committed nothing yet), and injects a second continuation into the same session.

The window the lock leaves open is therefore not "two turns overlap". It is "two daemons read the same interrupted tail and both act on it", and that is what a claim closes: a durable row saying *this specific interruption has already been continued by somebody*. It needs no new lease semantics and no hook that does not exist, because it is not a lock — it is a fact, and it stays true after the writer has gone away.

Holding agent_run_lock across the turn instead would read like session-level mutual exclusion without being it. Ordinary turns take no lock at all — not attach-driven turns, not wake-loop turns, not the local REPL — so a lock held across the continuation excludes another continuation and nothing else. A reader would infer an invariant the code does not have, which is worse than the narrow scope being visible.

Package eventlog is the durable, append-only audit log that backs agent.Agent's session.Service. Each event the ADK runner appends to a session is persisted to the underlying database (SQLite, MySQL, or Postgres via GORM) and assigned a monotonic seq number. Subscribers can replay history with Since(fromSeq) or live-tail with Watch(fromSeq).

The package layers on top of ADK's session/database service: ADK owns the events / sessions / state tables, and we add a thin agent_eventlog overlay table whose rows reference ADK's events by id and add the seq column. Two GORM connections (ADK's and ours) share the same database file/DSN — atomic-across-tables writes are not provided in v1; the AppendEvent path writes ADK first, then the overlay, and surfaces overlay-write errors so callers can retry (event_id is unique-indexed for safe idempotency).

See docs/eventlog-plan.md and docs/eventlog-decisions.md for the design rationale and milestone breakdown.

Index

Constants

View Source
const (
	// EffectsAckTimeKey is the session-state key under which AckEffects records
	// the operator's acknowledgement watermark for ambiguous prior effects.
	EffectsAckTimeKey = "mast_effects_ack_time"
	// EffectsAckReasonKey is the session-state key under which AckEffects records
	// the operator's acknowledgement reason.
	EffectsAckReasonKey = "mast_effects_ack_reason"
	// EffectsAckByKey is the session-state key under which AckEffects records
	// the operator identity.
	EffectsAckByKey = "mast_effects_ack_by"
	// RedactionApproverDigest is the default export mode: human approvers are
	// replaced with approval.RedactApprover's SHA-256 prefix, and machine
	// identities pass through in the clear.
	RedactionApproverDigest = "approver-sha256"
	// RedactionNone marks an export written with IncludeApprover: true.
	RedactionNone = "none"

	// AwaitingApproval indicates a session is parked on a write-gate confirmation.
	AwaitingApproval = "approval"
	// AwaitingInput indicates a session is parked on an operator input question.
	AwaitingInput = "input"
)
View Source
const (
	// MetadataKeyCaller is the effective Caller.Identity that
	// originated the turn this event belongs to. Empty when no auth
	// context was available (legacy / single-user / out-of-band code
	// paths).
	MetadataKeyCaller = "caller"
	// MetadataKeyProxyBy is set when the effective Caller was
	// asserted via the proxy path (X-Asserted-Caller header): records
	// the proxying identity (e.g., "sa:slack-bot"). Empty for direct
	// authentication.
	MetadataKeyProxyBy = "proxy_by"
)

MetadataKey* are the well-known keys agent.Agent uses when wiring the per-request caller context into the eventlog metadata sidecar. They're exported so audit consumers can read what's there without guessing at conventions.

View Source
const (

	// DefaultTokenTTL is the default resume-token lifetime.
	DefaultTokenTTL = 7 * 24 * time.Hour

	// PlaneGate and PlaneInterrupt identify the two pause planes recorded in PauseRecord.Plane.
	PlaneGate      = "gate"
	PlaneInterrupt = "interrupt"
)
View Source
const FinishReasonMetadataKey = "finish_reason"

FinishReasonMetadataKey is the CustomMetadata key under which AppendEvent records a model turn's genai FinishReason before persist. ADK's storage row has no FinishReason column (createEventFromStorageEvent drops it), but it DOES round-trip CustomMetadata — so stamping the reason here is what lets a reloaded event distinguish a MAX_TOKENS truncation (resume-able) from a normal STOP completion. Read by pkg/agent's auto-continue classifier (#582); mirrors the CompactionMetadataKey piggy-back the classifier already consults.

View Source
const ModelVersionMetadataKey = "model_version"

ModelVersionMetadataKey is the CustomMetadata key under which AppendEvent records a model turn's LLMResponse.ModelVersion before persist (#1359). ADK's storageEvent has no ModelVersion column (createEventFromStorageEvent drops it), so without this stamp a reloaded event loses its model identity and RebuildTrackerFromEvents falls back to the parent session's default model.

Variables

View Source
var (
	ErrTokenNotFound  = fmt.Errorf("eventlog: resume token not found: %w", gorm.ErrRecordNotFound)
	ErrTokenExpired   = errors.New("eventlog: resume token expired")
	ErrAlreadyResumed = errors.New("eventlog: pause already resumed")
)

Pause/token sentinel errors.

View Source
var ErrClosed = errors.New("eventlog: stream is closed")

ErrClosed is returned by Stream methods invoked after Close.

View Source
var ErrLeaseLost = errors.New("eventlog: session lease lost")

ErrLeaseLost is returned by consumers of SessionLock.Lost (such as autonomous.Resume) when a held session lease is stolen by another process or its heartbeat fails past the staleness window (#1361).

View Source
var ErrSessionLocked = errors.New("eventlog: session is locked by another process")

ErrSessionLocked is returned by AcquireLock when another live process already holds the lease. The error message includes the holder identifier so operators can diagnose contention.

View Source
var ErrUnscopedQuery = errors.New("eventlog: query must be scoped to a session or session tree")

ErrUnscopedQuery is what a Stream returns (wrapped) from Since or Watch when the query names no session ID (neither ForSession nor WithSessionTree with a non-empty one) and the implementation cannot serve a query across its whole store. It is yielded before any entry and before Watch blocks. The SQL implementation never returns it. It is exported ahead of the first implementation that does, so a caller that reads across sessions (an audit dashboard, say) can handle it with errors.Is from the start.

Functions

func IsSessionNotFound

func IsSessionNotFound(err error) bool

IsSessionNotFound reports whether err means "that session is not in the log", as opposed to a real failure to read it.

ADK's database session service wraps GORM's ErrRecordNotFound with %w behind the text "database error while fetching session", which reads like a database fault and is not one — a session that has never been written is the ordinary state of every session before its first event. Callers that treat any non-nil error as a problem log a scary line on a healthy cold boot; this is the check that tells the two apart without matching on message text.

It lives here rather than in the callers because the GORM coupling is this package's to own.

func ValidReasons added in v3.1.0

func ValidReasons() []string

ValidReasons lists the accepted Reason values.

Types

type AckRecord added in v3.1.0

type AckRecord struct {
	Workload  string    `json:"workload"`
	Subject   string    `json:"subject"`
	By        string    `json:"by"`
	ProxyBy   string    `json:"proxy_by,omitempty"`
	Reason    string    `json:"reason,omitempty"`
	At        time.Time `json:"at"`
	Forwarded bool      `json:"forwarded"`
}

AckRecord is the durable operator acknowledgement of an active monitoring subject (`Transition.SubjectKey`), stored in ADK session state on the reserved `"mast-acks:mast-ops"` session.

An ack is an operational signal suppressing monitor.notify.remind_after reminders for an open subject; it is NOT an approval of a gated tool call and never writes a DecisionRecord.

type BootRecord

type BootRecord struct {
	BootAt    time.Time
	Attempted []string
}

BootRecord is the public view of one boot-scan run.

type BranchLister

type BranchLister interface {
	Branches(ctx context.Context, opts ...QueryOption) ([]string, error)
}

BranchLister is an OPTIONAL Stream extension: report the distinct branch labels that exist under a query's filters, without hydrating a single event.

It answers "what ran here?", which the Since/Watch pair can only answer by reading every row and looking at the branch column. The caller that needs it is the attach layer's subagent-events endpoint: a subagent declared as "cluster" writes its turns under the branch the runner minted for the instance ("bg.cluster-1"), so resolving a name to its branches means asking the log which branches are there (go-steer/core-agent#694).

Not part of Stream itself — adding a method to a published interface breaks every implementation outside this repo. Type-assert for it and degrade when it's absent:

if bl, ok := stream.(eventlog.BranchLister); ok { ... }

Honors the same QueryOptions as Since, including WithLimit (a cap on the number of DISTINCT labels returned, not on rows scanned). Labels come back sorted, and the empty branch — the parent session's own turns — is omitted.

type DecisionStore added in v3.1.0

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

DecisionStore persists write-gate Decision records in agent_approval_decisions. A nil *DecisionStore is a safe no-op.

func NewDecisionStore added in v3.1.0

func NewDecisionStore(ctx context.Context, db *gorm.DB) (*DecisionStore, error)

NewDecisionStore constructs a DecisionStore over an existing GORM connection and AutoMigrates agent_approval_decisions.

func (*DecisionStore) HasDecision added in v3.1.0

func (s *DecisionStore) HasDecision(ctx context.Context, sessionID, functionCallID string) (bool, error)

HasDecision reports whether a Decision record for functionCallID in sessionID exists in agent_approval_decisions. It matches approval.DecisionLookup so write-gate plugins can detect pre-crash dispatches across process restarts (#1400, mast #561).

func (*DecisionStore) ListDecisions added in v3.1.0

func (s *DecisionStore) ListDecisions(ctx context.Context, sessionID string) ([]approval.Decision, error)

ListDecisions returns the durable decisions recorded in SQL for sessionID (or across all sessions when sessionID is empty), oldest first.

func (*DecisionStore) RecordDecision added in v3.1.0

func (s *DecisionStore) RecordDecision(ctx context.Context, d approval.Decision) error

RecordDecision persists a write-gate Decision record before tool execution.

type Entry

type Entry struct {
	// Seq orders entries within one root session tree; see the
	// Stream doc for what it does and does not promise.
	Seq      int64
	Event    *session.Event
	Metadata map[string]string
}

Entry is one row from the event log: the assigned seq plus the underlying ADK session.Event (loaded via the paired session.Service).

Metadata is an optional sidecar map populated by a MetadataExtractor (see WithMetadataExtractor). The eventlog package itself is agnostic to the keys — agent.Agent wires an extractor that pulls auth.Caller.Identity (key "caller") and proxy attribution (key "proxy_by") from the request context. Rows persisted before the sidecar column shipped read back as a nil Metadata map.

type ExportMeta added in v3.1.0

type ExportMeta struct {
	Schema     string     `json:"schema"`
	Tool       string     `json:"tool"`
	ExportedAt time.Time  `json:"exported_at"`
	Source     string     `json:"source,omitempty"`
	Session    string     `json:"session,omitempty"`
	Workload   string     `json:"workload,omitempty"`
	Since      *time.Time `json:"since,omitempty"`
	Until      *time.Time `json:"until,omitempty"`
	Redaction  string     `json:"redaction"`
	Warning    string     `json:"warning"`
	Records    int        `json:"records"`
}

ExportMeta is the provenance object on the first line of an export.

type ExportOptions added in v3.1.0

type ExportOptions struct {
	AppName         string
	UserID          string
	SessionID       string
	Workload        string
	Since           time.Time
	Until           time.Time
	IncludeApprover bool
	Source          string
	Tool            string
}

ExportOptions scopes a decision export.

type GuardrailState added in v3.1.0

type GuardrailState struct {
	AppName            string  `gorm:"primaryKey;not null"`
	UserID             string  `gorm:"primaryKey;not null"`
	SessionID          string  `gorm:"primaryKey;not null"`
	WatchdogTripped    bool    `gorm:"not null;default:false"`
	WatchdogReason     string  `gorm:"type:text"`
	CostTripped        bool    `gorm:"not null;default:false"`
	CostReason         string  `gorm:"type:text"`
	BudgetExtensionUSD float64 `gorm:"not null;default:0"`
	// LastEventID records the most recent reset event ID that added to
	// BudgetExtensionUSD so fallback retries cannot double-apply an
	// additive budget extension (trip/clear assignments are naturally
	// idempotent).
	LastEventID string    `gorm:"type:text"`
	UpdatedAt   time.Time `gorm:"autoUpdateTime"`
}

GuardrailState is the durable row in agent_guardrail_state tracking whether a session's watchdog or cost ceiling has tripped and any cumulative operator-granted budget extensions (#1360).

func (GuardrailState) TableName added in v3.1.0

func (GuardrailState) TableName() string

TableName pins the GORM table name across database drivers.

type GuardrailStore added in v3.1.0

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

GuardrailStore persists guardrail trip, reset, and budget-extension state synchronously to the database so a tripped session remains tripped across restarts and RestoreGuardrails reads current state by primary key without hydrating the session history (#1360, #1438). Sessions created through eventlog.Handle.Service seed a zero state row on creation; pre-upgrade sessions without a state row perform a one-time indexed check on agent_eventlog and backfill or seed the row so subsequent reads are O(1) primary-key lookups.

func NewGuardrailStore added in v3.1.0

func NewGuardrailStore(ctx context.Context, db *gorm.DB) (*GuardrailStore, error)

NewGuardrailStore auto-migrates agent_guardrail_state on db and returns a ready GuardrailStore.

func (*GuardrailStore) AddBudgetExtension added in v3.1.0

func (s *GuardrailStore) AddBudgetExtension(ctx context.Context, appName, userID, sessionID string, addUSD float64) error

AddBudgetExtension adds a positive USD budget extension to the session's durable guardrail state. Non-positive addUSD is a no-op.

func (*GuardrailStore) ClearCost added in v3.1.0

func (s *GuardrailStore) ClearCost(ctx context.Context, appName, userID, sessionID string) error

ClearCost clears a durable cost-ceiling trip for the session.

func (*GuardrailStore) ClearWatchdog added in v3.1.0

func (s *GuardrailStore) ClearWatchdog(ctx context.Context, appName, userID, sessionID string) error

ClearWatchdog clears a durable watchdog trip for the session.

func (*GuardrailStore) Load added in v3.1.0

func (s *GuardrailStore) Load(ctx context.Context, appName, userID, sessionID string) (GuardrailState, error)

Load returns the current GuardrailState for the session in O(1) by primary key, or a zero GuardrailState when no row has been recorded.

func (*GuardrailStore) LoadWithLegacyCheck added in v3.1.0

func (s *GuardrailStore) LoadWithLegacyCheck(ctx context.Context, appName, userID, sessionID string) (GuardrailState, bool, error)

LoadWithLegacyCheck returns the session's GuardrailState from agent_guardrail_state in O(1) by primary key when a state or sentinel row is present. When no row exists yet (e.g. a pre-upgrade session), it probes agent_eventlog via idx_agent_eventlog_session_author in O(log N) to report whether pre-upgrade guardrail events need a one-time fold and backfill; when none exist and the session is present in storage, it seeds a zero sentinel row so future calls hit the primary key directly (#1360, #1438).

func (*GuardrailStore) SaveState added in v3.1.0

func (s *GuardrailStore) SaveState(ctx context.Context, st GuardrailState) error

SaveState writes a full GuardrailState snapshot for the session. Used by RestoreGuardrails when backfilling a pre-upgrade session whose guardrail events predated agent_guardrail_state (#1360).

func (*GuardrailStore) TripCost added in v3.1.0

func (s *GuardrailStore) TripCost(ctx context.Context, appName, userID, sessionID, reason string) error

TripCost records a durable cost-ceiling trip for the session.

func (*GuardrailStore) TripWatchdog added in v3.1.0

func (s *GuardrailStore) TripWatchdog(ctx context.Context, appName, userID, sessionID, reason string) error

TripWatchdog records a durable watchdog trip for the session.

type Handle

type Handle struct {
	// Stream is the seq + replay + watch primitive.
	Stream Stream
	// Service is the session.Service backed by the same database.
	// Pass to agent.WithSessionService (or use the
	// agent.WithEventLog convenience that does both at once).
	Service session.Service
	// Guardrail is the durable O(1) guardrail state store backed by
	// agent_guardrail_state on the same database (#1360). Nil on a
	// non-SQL Handle.
	Guardrail *GuardrailStore
	// Spend is the durable append-only spend ledger backed by
	// agent_budget_spend on the same database (#1359). Nil on a
	// non-SQL Handle.
	Spend *SpendStore
	// Decisions is the durable write-gate decision store backed by
	// agent_approval_decisions on the same database (#1400). Nil on a
	// non-SQL Handle.
	Decisions *DecisionStore
	// DB exposes the overlay-table connection so adjacent
	// substrates (e.g., pkg/attach.SessionACLStore) can share the
	// same database without re-opening it. Read-only access from
	// outside pkg/eventlog — mutations happen via the typed
	// stores. Nil before Open returns. Close closes the pool but
	// leaves the field set.
	//
	// DB is only ever set by a SQL-backed Handle; a Handle built on a
	// non-SQL store leaves it nil. Read a nil DB as "this Handle has
	// no SQL connection to share", never as "closed" or "unhealthy":
	// use Ping for that.
	DB *gorm.DB
	// contains filtered or unexported fields
}

Handle bundles the Stream with the session.Service that writes to the same database. agent.WithEventLog(handle) wires both into an agent.Agent in one call.

func Open

func Open(ctx context.Context, dialector gorm.Dialector, opts ...Option) (*Handle, error)

Open constructs a Handle backed by the supplied GORM dialector. Pass any standard dialector (sqlite.Open, postgres.Open, mysql.Open).

Open does several things:

  • Constructs ADK's database.SessionService against the dialector and runs its AutoMigrate so the events / sessions / state tables exist.
  • Opens a second GORM connection for our overlay table and AutoMigrates agent_eventlog.
  • For SQLite (detected via the dialector's Name()), enables WAL journal mode so concurrent readers can run alongside the writer. Disable with WithSkipWAL.
  • Wraps the ADK service so AppendEvent writes to both layers.

func (*Handle) Ack added in v3.1.0

func (h *Handle) Ack(ctx context.Context, appName, workload, subject string) (*AckRecord, error)

Ack looks up the durable AckRecord for (workload, subject). It returns (nil, nil) when no acknowledgement has been recorded.

func (*Handle) AckEffects added in v3.1.0

func (h *Handle) AckEffects(ctx context.Context, appName, userID, sessionID, by, reason string) (time.Time, error)

AckEffects appends an operator acknowledgement watermark for ambiguous prior effects on sessionID. Dangling mutating tool calls at or before the returned timestamp no longer trip the outbox's ambiguous-effect refusal mode.

func (*Handle) Acks added in v3.1.0

func (h *Handle) Acks(ctx context.Context, appName, workload string) ([]AckRecord, error)

Acks returns all recorded acknowledgements for workload (or across all workloads when workload is empty), ordered by At ascending.

func (*Handle) AcquireLock

func (h *Handle) AcquireLock(ctx context.Context, app, user, session string) (*SessionLock, error)

AcquireLock takes an exclusive lease on (app, user, session) for the lifetime of the returned *SessionLock. Returns ErrSessionLocked if another process holds a fresh lease (heartbeat within staleAfter); steals the lease if the existing holder's heartbeat is older than staleAfter (indicating a crashed process).

The lease is heartbeated automatically until SessionLock.Release is called; Release is idempotent and safe to defer.

func (*Handle) ClaimContinuation

func (h *Handle) ClaimContinuation(ctx context.Context, app, user, session string, interruptedAt time.Time, holder string) (bool, error)

ClaimContinuation records that the caller is about to inject a continuation for the interruption at interruptedAt, and reports whether the claim is the caller's to act on.

false means the interruption at that exact instant has already been claimed — by this daemon on an earlier pass, or by a peer sharing the database — and the caller must stand down rather than inject a second continuation for the same interruption. true means the row now names the caller.

A *later* interruption is a different fact and always claimable: the row carries one instant, not a flag, so a session interrupted again after a continuation has run gets continued again. That is the whole point of keying on the interruption rather than on the session. A claim older than continuationClaimTTL is also re-claimable; see that constant for why an eternal claim would be a deadlock.

Atomic in one statement rather than read-then-write. Every in-tree caller already holds the session run lock, so the compare-and-set is belt and braces — but a claim whose correctness depends on a lock taken somewhere else is exactly the kind of invariant that quietly stops being true, and one conditional upsert costs nothing to make honest.

func (*Handle) Close

func (h *Handle) Close() error

Close releases all resources held by the Handle (Stream + the underlying database connection). Safe to call multiple times.

func (*Handle) ConsumeScheduled added in v3.1.0

func (h *Handle) ConsumeScheduled(ctx context.Context, appName, token, by string) (*PauseRecord, error)

ConsumeScheduled consumes a token on behalf of the timed-pause scheduler without enforcing token TTL.

func (*Handle) ConsumeToken added in v3.1.0

func (h *Handle) ConsumeToken(ctx context.Context, appName, token, by string) (*PauseRecord, error)

ConsumeToken marks the token's pause record consumed, enforcing token TTL.

func (*Handle) EffectsAckedAt added in v3.1.0

func (h *Handle) EffectsAckedAt(ctx context.Context, appName, userID, sessionID string) (time.Time, bool)

EffectsAckedAt returns the session's effects-acknowledgement watermark, if one was recorded. Read failures and missing markers report false.

func (*Handle) ExportDecisions added in v3.1.0

func (h *Handle) ExportDecisions(ctx context.Context, w io.Writer, opts ExportOptions) (int, error)

ExportDecisions writes the store's write-gate Decision records to w as JSON Lines, preceded by one ExportMeta provenance line, and returns the number of decision rows written.

func (*Handle) ExtendToken added in v3.1.0

func (h *Handle) ExtendToken(ctx context.Context, appName, token string, ttl time.Duration) (*PauseRecord, error)

ExtendToken moves an active token's expiry to now + ttl.

func (*Handle) FindToken added in v3.1.0

func (h *Handle) FindToken(ctx context.Context, appName, token string) (*PauseRecord, error)

FindToken resolves a resume token to its pause record (active or consumed).

func (*Handle) GatePause added in v3.1.0

func (h *Handle) GatePause(ctx context.Context, appName, userID, sessionID string) *PauseRecord

GatePause returns the session's active gate-pause record, if any.

func (*Handle) HasDecision added in v3.1.0

func (h *Handle) HasDecision(ctx context.Context, sessionID, functionCallID string) (bool, error)

HasDecision delegates to Handle.Decisions.HasDecision.

func (*Handle) ListParks added in v3.1.0

func (h *Handle) ListParks(ctx context.Context, appName, userID, sessionID string) ([]SessionParkedCalls, error)

ListParks returns the open parks for one session (when sessionID is non-empty) or across all sessions under appName. When sessionID is empty, only sessions with at least one open park are returned.

func (*Handle) PauseGate added in v3.1.0

func (h *Handle) PauseGate(ctx context.Context, appName, userID, sessionID string, spec PauseSpec) (PauseHandle, bool, error)

PauseGate writes or updates a session's plane-B gate pause.

func (*Handle) PauseInterrupt added in v3.1.0

func (h *Handle) PauseInterrupt(ctx context.Context, appName, userID, sessionID, interruptID string, spec PauseSpec) (PauseHandle, error)

PauseInterrupt mints the plane-A pause record for a parked interrupt.

func (*Handle) PauseRecords added in v3.1.0

func (h *Handle) PauseRecords(ctx context.Context, appName, userID, sessionID string) (map[string]*PauseRecord, error)

PauseRecords returns all pause records for one session (active and consumed).

func (*Handle) Ping

func (h *Handle) Ping(ctx context.Context) error

Ping reports whether the event log is still readable, for use by a readiness probe (#946).

It issues a real bounded read against the overlay table rather than pinging the connection pool. On SQLite a pool ping proves almost nothing: the pool hands back a live *sql.DB whose file may since have been deleted, replaced, or locked by another writer, and database/sql only discovers that on a statement. One indexed row read is the cheapest query that actually touches the file.

A closed Handle reports ErrClosed rather than panicking, so a probe racing shutdown fails cleanly instead of taking the process with it.

func (*Handle) RecentBoots

func (h *Handle) RecentBoots(ctx context.Context, since time.Time) ([]BootRecord, error)

RecentBoots returns boot-scan records with BootAt >= since, oldest first. Rows with unparsable Attempted blobs are returned with a nil slice rather than dropped — the breaker counts boots, and losing a row to corruption would weaken the guard exactly when things are already going wrong.

func (*Handle) RecordAck added in v3.1.0

func (h *Handle) RecordAck(ctx context.Context, appName string, rec AckRecord) error

RecordAck persists rec into the reserved `"mast-acks:mast-ops"` session's durable state via AppendEvent StateDelta. Repeated acks for the same (Workload, Subject) overwrite the state entry in place.

func (*Handle) RecordBoot

func (h *Handle) RecordBoot(ctx context.Context, at time.Time, attempted []string) (uint, error)

RecordBoot appends a boot-scan record and returns the new row's ID. attempted lists the session IDs the scan triggered continuations for (empty slice = scan ran, found nothing). The returned ID lets a caller later narrow the row to the sessions that actually got a fair shot via UpdateBootAttempted — outcome-aware accounting for the write-ahead intent record (#575). AutoMigrate is idempotent and cheap at once-per-boot call frequency.

func (*Handle) RecordDecision added in v3.1.0

func (h *Handle) RecordDecision(ctx context.Context, d approval.Decision) error

RecordDecision delegates to Handle.Decisions.RecordDecision.

func (*Handle) ReleaseContinuationClaim

func (h *Handle) ReleaseContinuationClaim(ctx context.Context, app, user, session string, interruptedAt time.Time, holder string) error

ReleaseContinuationClaim gives back a claim whose injection did not happen, so the interruption can be claimed again immediately — by the retry driver on its next tick, or by a peer daemon — rather than after continuationClaimTTL.

Conditional on the claim still naming this interruption AND this holder, so a caller unwinding late cannot delete a successor's claim for a newer interruption.

Note the asymmetry with the claim itself: a claim that is never released is a continuation delayed by the TTL, and a release that never runs is the same. Both failure directions cost latency, and neither produces the duplicate this file exists to prevent — which is why callers log a failed release rather than retrying it.

func (*Handle) SaveSchedule added in v3.1.0

func (h *Handle) SaveSchedule(ctx context.Context, appName string, rec ScheduleRecord) error

SaveSchedule writes the workload's cadence state to the reserved "mast-scheduler:mast-ops" session, replacing any previous record for rec.Workload.

func (*Handle) ScanPauses added in v3.1.0

func (h *Handle) ScanPauses(ctx context.Context, appName string) ([]*PauseRecord, error)

ScanPauses walks every session's ops row under appName and returns all active pause records.

func (*Handle) Schedule added in v3.1.0

func (h *Handle) Schedule(ctx context.Context, appName, workload string) (*ScheduleRecord, error)

Schedule reads a workload's persisted cadence state, or (nil, nil) when no valid record is present.

Missing sessions, blanked keys, corrupt JSON, and anchor-less records all return (nil, nil) so the caller re-anchors on now rather than wedging the scheduled trigger.

func (*Handle) SessionDecisions added in v3.1.0

func (h *Handle) SessionDecisions(ctx context.Context, appName, userID, sessionID string) ([]approval.Decision, error)

SessionDecisions returns the write-gate Decision records for one session in the order the calls were adjudicated, merging records from the SQL DecisionStore and the session's event state deltas.

func (*Handle) UpdateBootAttempted

func (h *Handle) UpdateBootAttempted(ctx context.Context, id uint, attempted []string) error

UpdateBootAttempted rewrites the attempted-session list of an existing boot-log row (identified by the ID from RecordBoot). It exists to narrow a pessimistic write-ahead record down to the sessions a scan actually attempted, after synchronous skips (a run lock held by another daemon, a raced-clean tail) have been resolved — so those skips don't burn the per-session cumulative cap on daemons that never got a fair shot (#575, the fleet cap-burn). The write-ahead property is preserved: this only ever runs AFTER the intent record exists, so a daemon killed mid-scan leaves the full pessimistic list in place.

type MetadataExtractor

type MetadataExtractor func(ctx context.Context) map[string]string

MetadataExtractor pulls the per-event sidecar metadata from the context at Append time. Return nil (or empty map) to skip — empty maps round-trip as nil on the read side. Callers wire an extractor via WithMetadataExtractor; the default is no-op (preserves the pre-sidecar shape on disk).

The function is called inside Append's request context, so it can safely fetch request-scoped values without spawning goroutines.

type Option

type Option func(*openOpts)

Option configures Open.

func WithGORMConfig

func WithGORMConfig(c *gorm.Config) Option

WithGORMConfig overrides the gorm.Config used for the overlay connection. Useful for silencing the default logger in tests (gorm.Config{Logger: logger.Default.LogMode(logger.Silent)}).

func WithLockHeartbeat added in v3.1.0

func WithLockHeartbeat(interval, staleAfter time.Duration) Option

WithLockHeartbeat overrides the heartbeat cadence and staleness window used by Handle.AcquireLock (defaults: 5s interval, 30s staleness window). Non-positive arguments keep their respective defaults.

func WithMetadataExtractor

func WithMetadataExtractor(fn MetadataExtractor) Option

WithMetadataExtractor wires a function that produces sidecar metadata for each appended event. The map (JSON-encoded) is stored in the overlay row's metadata column and surfaces on Entry.Metadata at read time. Nil disables the sidecar (default).

agent.New wires an extractor that pulls the per-request caller + proxy attribution from the context so multi-session audit logs carry who triggered each event without coupling pkg/eventlog to pkg/auth.

func WithSkipWAL

func WithSkipWAL() Option

WithSkipWAL disables the automatic PRAGMA journal_mode=WAL set on SQLite databases at Open time. WAL is on by default because it permits concurrent readers alongside a writer; turn it off for in-memory databases or read-only setups where WAL adds no value.

func WithWatchInterval

func WithWatchInterval(d time.Duration) Option

WithWatchInterval sets the polling interval Watch uses to check for new rows. Default is 200ms. Smaller values reduce subscriber latency at the cost of database load; larger values do the opposite.

type ParkedCall added in v3.1.0

type ParkedCall struct {
	InterruptID    string             `json:"interrupt_id"`
	CallID         string             `json:"call_id,omitempty"`
	ToolName       string             `json:"tool_name,omitempty"`
	Awaiting       string             `json:"awaiting,omitempty"`
	Message        string             `json:"message,omitempty"`
	ProposedTool   string             `json:"proposed_tool,omitempty"`
	ProposedArgs   map[string]any     `json:"proposed_args,omitempty"`
	Subject        string             `json:"subject,omitempty"`
	Author         string             `json:"author,omitempty"`
	RaisedAt       time.Time          `json:"raised_at"`
	LongRunning    bool               `json:"long_running,omitempty"`
	ResponseSchema *jsonschema.Schema `json:"response_schema,omitempty"`
	Payload        any                `json:"payload,omitempty"`
}

ParkedCall is one open interrupt or long-running tool park on a session.

func ScanPendingParks added in v3.1.0

func ScanPendingParks(events session.Events) []ParkedCall

ScanPendingParks walks a session's event log in order and returns any RequestedInput or LongRunningToolIDs parks that have not been resolved by a later FunctionResponse.

type PauseHandle added in v3.1.0

type PauseHandle struct {
	Token     string    `json:"token"`
	SessionID string    `json:"session_id"`
	ExpiresAt time.Time `json:"expires_at"`
}

PauseHandle is returned when a pause record is minted or updated.

type PauseRecord added in v3.1.0

type PauseRecord struct {
	Token       string         `json:"token"`
	Plane       string         `json:"plane"`
	InterruptID string         `json:"interrupt_id,omitempty"`
	App         string         `json:"app"`
	User        string         `json:"user"`
	SessionID   string         `json:"session_id"`
	Reason      Reason         `json:"reason"`
	Message     string         `json:"message,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	MintedAt    time.Time      `json:"minted_at"`
	ExpiresAt   time.Time      `json:"expires_at"`
	ResumeAt    time.Time      `json:"resume_at,omitzero"`
	ConsumedAt  time.Time      `json:"consumed_at,omitzero"`
	ConsumedBy  string         `json:"consumed_by,omitempty"`
}

PauseRecord is the durable pause record and resume token stored on a session's companion ops row.

func (*PauseRecord) Active added in v3.1.0

func (r *PauseRecord) Active() bool

Active reports whether the record still gates or awaits a resume.

func (*PauseRecord) Expired added in v3.1.0

func (r *PauseRecord) Expired(now time.Time) bool

Expired reports whether the record's token has passed its TTL.

type PauseSpec added in v3.1.0

type PauseSpec struct {
	Reason    Reason
	Message   string
	Metadata  map[string]any
	ResumeAt  time.Time
	Interrupt bool
	TokenTTL  time.Duration
}

PauseSpec is the caller-facing pause request.

type QueryOption

type QueryOption func(*queryOpts)

QueryOption filters Since/Watch results.

func ForSession

func ForSession(appName, userID, sessionID string) QueryOption

ForSession restricts results to one session triple. Without it, queries scan across every session in the database — useful for audit dashboards, dangerous for high-volume reads. An empty argument is a wildcard, so ForSession(app, user, "") is unscoped too. Only the SQL implementation is promised to serve unscoped queries; others may refuse them with ErrUnscopedQuery (see the Stream doc).

func WithAnyBranchPrefix

func WithAnyBranchPrefix(prefixes ...string) QueryOption

WithAnyBranchPrefix matches events whose Branch begins with ANY of the supplied prefixes (an OR group, AND'd with the other filters).

One subagent is reachable under several branch spellings depending on how it was launched — a sync subagent tool tags its events with the bare name, the background runner with "bg.<name>", RunSubtask with "sub.<name>", the remote runner with "remote.<name>" — so an operator asking "what did subagent X do?" needs the union, not a single prefix (#638).

Empty prefixes are dropped: a caller building the list from user input can't accidentally widen the query to everything by passing "". LIKE metacharacters ('%', '_') in a prefix are escaped, so a prefix matches literally and only the intended subtree.

func WithAuthor

func WithAuthor(name string) QueryOption

WithAuthor matches events emitted by a specific author. The autonomous driver uses Author="<binary>/autonomous" for checkpoint events; consumer-supplied authors work the same way.

func WithAuthorSuffix

func WithAuthorSuffix(suffix string) QueryOption

WithAuthorSuffix matches events whose Author ends with the supplied suffix. Used by ResumeAutonomous to find checkpoint events regardless of which binary emitted them — checkpoints land with Author="<binary>/autonomous", so suffix "/autonomous" matches checkpoints from any core-agent-family process. Empty suffix is a no-op (matches everything).

func WithBranchPrefix

func WithBranchPrefix(prefix string) QueryOption

WithBranchPrefix matches events whose Branch field begins with prefix. Use to scope queries to a subagent subtree once Phase 4 of the eventlog plan ships subagent runners that set Branch.

Repeated calls accumulate and are OR'd together — see WithAnyBranchPrefix, which this delegates to.

func WithLimit

func WithLimit(n int) QueryOption

WithLimit caps the number of entries returned. Zero or negative is treated as no limit.

func WithSessionTree

func WithSessionTree(appName, userID, parentSessionID string) QueryOption

WithSessionTree restricts results to the parent session ID and any derived sub-session IDs. The subagent runner names its session "<parent>:sub:<branch>" by convention; this option's underlying SQL matches the parent + every "<parent>:sub:%" descendant in one query so an audit can pull the whole tree without a follow-up join.

When set, takes precedence over the (App, User, Session) triple from ForSession — the two are mutually exclusive in practice because WithSessionTree implies the (app, user) pair already. Mutually composable with the other QueryOptions (WithBranchPrefix, WithAuthor, WithAuthorSuffix, WithLimit).

type Reason added in v3.1.0

type Reason string

Reason is the pause-reason taxonomy.

const (
	ReasonBudgetExhaustion  Reason = "budget_exhaustion"
	ReasonWatchdogAnomaly   Reason = "watchdog_anomaly"
	ReasonCostCoolDown      Reason = "cost_cool_down"
	ReasonMaintenanceWindow Reason = "maintenance_window"
	ReasonRateLimitBackoff  Reason = "rate_limit_backoff"
	ReasonAmbiguity         Reason = "ambiguity"
	ReasonOperator          Reason = "operator"
	ReasonA2ATaskPending    Reason = "a2a_task_pending"
	ReasonOther             Reason = "other"
)

type ScheduleRecord added in v3.1.0

type ScheduleRecord struct {
	// Workload names the bundle or recipe this cadence belongs to.
	Workload string `json:"workload"`

	// Interval is the configured cadence duration at the time of the write.
	Interval time.Duration `json:"interval,omitempty"`

	// Anchor is the instant the cadence is counted from.
	Anchor time.Time `json:"anchor"`

	// LastTick is the most recent lattice point accounted for — fired,
	// or coalesced away as a missed tick.
	LastTick time.Time `json:"last_tick,omitempty"`

	// LastFire is when the last fire actually started (tick + jitter),
	// and Fires counts the fires this schedule has driven since the
	// anchor was set.
	LastFire time.Time `json:"last_fire,omitempty"`
	Fires    int64     `json:"fires,omitempty"`
}

ScheduleRecord is one workload's persisted cadence state.

The anchor is the instant the cadence is counted from: the moment the daemon first saw this workload's schedule. Every fire lands on Anchor + k*Interval, so a daemon returning from a restart preserves the workload's phase instead of re-anchoring to process boot time.

type SessionLock

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

SessionLock is the lease returned by Handle.AcquireLock. It runs a background goroutine that refreshes heartbeat_at every heartbeatInterval until Release is called. Safe to call Release multiple times.

func (*SessionLock) Holder

func (l *SessionLock) Holder() string

Holder returns the identifier we registered when acquiring the lock. Useful for diagnostics + for tests that need to assert the row content.

func (*SessionLock) Lost

func (l *SessionLock) Lost() <-chan struct{}

Lost returns a channel that is closed if the lease is lost while it is held: either the heartbeat's conditional UPDATE matched zero rows — another process reclaimed the lease after our heartbeat lapsed past the staleness window (a long GC pause, sleep, or DB stall) — or heartbeats have failed to reach the database for the loss window (staleAfter minus one heartbeat interval), after which we can no longer prove exclusivity. A caller running work under the lock — e.g. the autonomous run loop — must select on this channel and abort promptly, otherwise both processes run against the same session: the exact split-brain the lock exists to prevent. Reaffirm tells the two causes apart after the fact. The channel is never closed for a lock that is cleanly Released while still held.

func (*SessionLock) Reaffirm added in v3.1.0

func (l *SessionLock) Reaffirm(ctx context.Context) (bool, error)

Reaffirm re-proves ownership with one conditional heartbeat UPDATE and reports whether this holder still owns the row. It exists for the moment after Lost() has closed because heartbeats STALLED (not because the row was stolen): in a single-replica deployment nobody took the lease during the outage, and a caller that can prove that may still write its final checkpoint. A stolen lease reports false without touching the database. The query is bounded by heartbeatTimeout.

func (*SessionLock) Release

func (l *SessionLock) Release() error

Release ends the lease and stops the heartbeat goroutine. Idempotent; safe to defer.

type SessionParkedCalls added in v3.1.0

type SessionParkedCalls struct {
	SessionID string       `json:"session_id"`
	UserID    string       `json:"user_id,omitempty"`
	Awaiting  string       `json:"awaiting"`
	Pending   []ParkedCall `json:"pending"`
}

SessionParkedCalls groups a session's open parks with its awaiting classification.

type SpendRecord added in v3.1.0

type SpendRecord struct {
	Author   string
	Tokens   int64
	CostUSD  float64
	Unpriced bool
	// At is the wall-clock time of the call. Zero means "now".
	At time.Time

	// EventID is the ledger's idempotency key within a session: a
	// second Append with the same (app, user, session, EventID) is a
	// no-op. Empty makes no idempotency claim — the row is stored
	// with a NULL key and never deduplicated.
	EventID string
	// Model and Backend are what the call was priced on
	// (usage.Turn.Model / usage.Turn.Backend).
	Model   string
	Backend string
	// Side marks a call recorded with usage.Tracker.AppendSideUsage.
	Side bool
	// Token buckets, as on usage.Turn. Tokens above is their sum for
	// the Fold aggregate; these are what a restored Turn is built from.
	InputTokens              int64
	CachedInputTokens        int64
	CacheCreationInputTokens int64
	OutputTokens             int64
	ThoughtsTokens           int64
	ToolUseTokens            int64
}

SpendRecord is one priced model call recorded in agent_budget_spend.

Author is the event's author or model attribution verbatim. CostUSD is what the call cost when it was made, priced by the catalog in force at the time. Unpriced marks a call the catalog could not price, so a restored figure preserves the same unpriced-turn signal a live tracker carries.

The remaining fields (#1433) carry the per-call shape a usage.Tracker needs to be restored from the ledger without re-pricing: the model and backend the call was billed on, the token buckets, whether it was a side call, and the event it was committed on.

type SpendState added in v3.1.0

type SpendState struct {
	Session  SpendTotals
	ByAuthor map[string]SpendTotals
	// Unpriced counts calls the catalog could not price.
	Unpriced int
}

SpendState is what folding a session's ledger produces: the session's total, and the same rows broken out by author so per-subagent or per-model ceilings come back too.

Session includes every call ByAuthor also accounts for — the two are projections of the same rows, computed in the same query.

type SpendStore added in v3.1.0

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

SpendStore persists and folds a session's per-call spend (#1359).

A nil *SpendStore is usable and does nothing: Append is a no-op and Fold reports empty state — the "no durable store configured" case at the call sites, same shape as GuardrailStore.

Safe for concurrent use.

func NewSpendStore added in v3.1.0

func NewSpendStore(ctx context.Context, db *gorm.DB) (*SpendStore, error)

NewSpendStore constructs a store over an existing GORM connection — typically Handle.DB, the connection the guardrail store and pkg/attach's session ACL store already share. AutoMigrates agent_budget_spend; safe against an existing database.

func (*SpendStore) Append added in v3.1.0

func (s *SpendStore) Append(ctx context.Context, app, user, sid string, rec SpendRecord) error

Append writes one call's spend.

Idempotent on rec.EventID (#1433): a row already present for (app, user, sid, EventID) is left alone and no error is returned — `ON CONFLICT DO NOTHING` on SQLite and Postgres, which GORM's MySQL dialector renders as `ON DUPLICATE KEY UPDATE` of the key to itself. An empty EventID is stored as NULL and is never deduplicated.

func (*SpendStore) AppendBatch added in v3.1.0

func (s *SpendStore) AppendBatch(ctx context.Context, app, user, sid string, recs []SpendRecord) error

AppendBatch writes multiple spend rows atomically in a single transaction, with the same EventID idempotency semantics as Append (#1433). Used when seeding a pre-ledger session's historical turns so a transient mid-replay error never commits a partial ledger.

func (*SpendStore) Fold added in v3.1.0

func (s *SpendStore) Fold(ctx context.Context, app, user, sid string) (SpendState, error)

Fold reconstructs the session's spend from its ledger.

One GROUP BY author, summed in the database rather than in Go: the ledger is one row per model call, and a long-running session is the case this exists for.

A session with no rows folds to the zero value and no error.

func (*SpendStore) FoldTree added in v3.1.0

func (s *SpendStore) FoldTree(ctx context.Context, app, user, parentSID string) (SpendState, error)

FoldTree reconstructs the spend across a root session and every derived "<parent>:sub:..." sub-session in its tree, matching the scoping of WithSessionTree (#1359).

func (*SpendStore) History added in v3.1.0

func (s *SpendStore) History(ctx context.Context, app, user, sid string) ([]SpendRecord, error)

History returns the session's spend rows oldest-first — the per-call cost trail behind a folded total.

func (*SpendStore) HistoryTree added in v3.1.0

func (s *SpendStore) HistoryTree(ctx context.Context, app, user, parentSID string) ([]SpendRecord, error)

HistoryTree is History over a root session and every derived "<parent>:sub:..." sub-session in its tree, oldest-first across the whole tree — the rows a resumed session's usage.Tracker is restored from (#1433). Empty, with no error, for a session with no rows.

type SpendTotals added in v3.1.0

type SpendTotals struct {
	Tokens  int64
	CostUSD float64
	Calls   int
}

SpendTotals is one accumulator's folded form.

type Stream

type Stream interface {
	// Append writes ev to the log under sess. Returns the assigned
	// seq number. The event itself is also expected to be persisted
	// via the paired session.Service.AppendEvent. In the SQL
	// implementation Stream.Append only writes the overlay row that
	// carries the seq.
	//
	// Most callers don't invoke this directly; agent.Run drives the
	// session.Service which in turn calls Append internally.
	Append(ctx context.Context, sess session.Session, ev *session.Event) (seq int64, err error)

	// Since returns events with seq > fromSeq, in seq order. Bounded
	// by current end-of-log; returns when caught up. Apply filters
	// via QueryOption (ForSession, WithBranchPrefix, WithAuthor,
	// WithLimit). An unscoped call may yield ErrUnscopedQuery; see
	// the Stream doc.
	Since(ctx context.Context, fromSeq int64, opts ...QueryOption) iter.Seq2[Entry, error]

	// Watch returns events with seq > fromSeq, in seq order, blocking
	// for new events as they're appended. Cancel ctx to stop. Same
	// QueryOptions as Since, and the same scoping rule.
	//
	// How new events are noticed is implementation-defined. The SQL
	// implementation polls the database, by default every 200ms,
	// configurable via Open's WithWatchInterval option.
	Watch(ctx context.Context, fromSeq int64, opts ...QueryOption) iter.Seq2[Entry, error]

	// Close releases resources held by the Stream (typically the
	// underlying gorm.DB connection pool). Safe to call multiple
	// times.
	Close() error
}

Stream is the append-only event log primitive. Implementations are expected to be safe for concurrent use.

What every implementation promises, and what it does not:

  • Seq is unique and strictly increasing within one root session tree. A session ID's root is the part before its first ":sub:"; its tree is the root plus every "<root>:sub:..." descendant, at any depth. An ID with no ":sub:" in it is its own root, which includes derived IDs such as "<sid>:digest". Seq is NOT promised to be unique across trees, so never compare or merge seqs from two different trees. The SQL implementation happens to assign one global sequence, which satisfies this.
  • A query scoped to one session is always served: ForSession or WithSessionTree with a non-empty session ID. Any other query (none of those options, or an empty session ID, which every option treats as a wildcard) may span trees, and may be refused with an error wrapping ErrUnscopedQuery by an implementation that cannot enumerate its whole store. The SQL implementation serves every query.

docs/external-state-design.md is why the contract stops there.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL