sessionclassification

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package sessionclassification owns the session-classification feature policy.

Index

Constants

View Source
const (
	// MaxIgnoredUserAgentPrefixes bounds the configured literal exclusion list.
	MaxIgnoredUserAgentPrefixes = 16
	// MaxIgnoredUserAgentPrefixBytes caps each normalized exclusion prefix.
	MaxIgnoredUserAgentPrefixBytes = 128
	// MaxWorkspaceMarkers bounds marker inspection for one evaluation.
	MaxWorkspaceMarkers = 32
	// MaxWorkspaceMarkerBytes caps each workspace marker inspected by policy.
	MaxWorkspaceMarkerBytes = 128
	// MaxRemoteAttemptsPerSession bounds configured remote attempts.
	MaxRemoteAttemptsPerSession = 5
	// MinRemoteTimeout is the smallest allowed remote timeout.
	MinRemoteTimeout = time.Millisecond
	// MaxRemoteTimeout caps a single remote decision timeout.
	MaxRemoteTimeout = 30 * time.Second
	// MaxRemoteLeaseTTL bounds the shared remote decision lease.
	MaxRemoteLeaseTTL = 2 * time.Minute
	// MaxRemoteRetryBackoff bounds the delay between remote attempts.
	MaxRemoteRetryBackoff = 30 * time.Second
	// RemoteLeaseSafetyMargin ensures lease expiry follows the hard timeout.
	RemoteLeaseSafetyMargin = 100 * time.Millisecond
)
View Source
const (
	// MaxAuthorityIDBytes bounds proxy-owned identifiers retained by this feature.
	MaxAuthorityIDBytes = 256
	// MaxRemoteLeaseIDBytes bounds the opaque control token for a remote attempt.
	MaxRemoteLeaseIDBytes = 64
)
View Source
const ID = "session-classification"

Variables

View Source
var (
	// ErrNoAuthority means the session view contains no proxy-owned scope.
	ErrNoAuthority = errors.New("session classification: no proxy authority")
	// ErrInvalidKey means an authority key is malformed or outside its fixed bound.
	ErrInvalidKey = errors.New("session classification: invalid authority key")
	// ErrInvalidProposal means a promotion is not a valid positive classification.
	ErrInvalidProposal = errors.New("session classification: invalid positive proposal")
	// ErrInvalidRemoteOptions means a remote attempt limit or duration is outside its finite bounds.
	ErrInvalidRemoteOptions = errors.New("session classification: invalid remote claim bounds")
	// ErrStoreCapacity means a new authoritative record cannot be admitted without evicting retained state.
	ErrStoreCapacity = errors.New("session classification: store capacity reached")
	// ErrStaleRemoteClaim means a completion no longer owns the active remote lease.
	ErrStaleRemoteClaim = errors.New("session classification: stale remote claim")
	// ErrInvalidRemoteClaim means a remote completion token is malformed.
	ErrInvalidRemoteClaim = errors.New("session classification: invalid remote claim")
	// ErrInvalidStoreContext means a store operation received a nil context.
	ErrInvalidStoreContext = errors.New("session classification: nil store context")
	// ErrInvalidStoreTime means a store operation received a zero timestamp.
	ErrInvalidStoreTime = errors.New("session classification: invalid store time")
	// ErrLeaseNonce means the bounded lease nonce could not be created or validated.
	ErrLeaseNonce = errors.New("session classification: remote lease nonce unavailable")
	// ErrLeaseSequenceExhausted means the process-local lease sequence has no remaining values.
	ErrLeaseSequenceExhausted = errors.New("session classification: remote lease sequence exhausted")
	// ErrInvalidStoreConfig means the in-memory adapter bounds are invalid.
	ErrInvalidStoreConfig = errors.New("session classification: invalid memory store bounds")
)

Functions

func RoundRemoteDeadlineUpToMicrosecond

func RoundRemoteDeadlineUpToMicrosecond(deadline time.Time) time.Time

RoundRemoteDeadlineUpToMicrosecond rounds a remote lease or retry deadline upward to the shared durable timestamp precision. Keeping expiry deadlines aligned lets SQLite, PostgreSQL, and memory stores enforce identical eligibility boundaries without allowing a deadline to expire early.

func ValidateKey

func ValidateKey(key Key) error

ValidateKey checks the bounded opaque authority without normalizing it.

func ValidatePositiveProposal

func ValidatePositiveProposal(proposal session.Classification) error

ValidatePositiveProposal checks that a promotion contains a valid positive snapshot.

func ValidateStoreContext

func ValidateStoreContext(ctx context.Context) error

ValidateStoreContext rejects nil contexts and propagates cancellation.

func ValidateStoreTime

func ValidateStoreTime(now time.Time) error

ValidateStoreTime rejects an absent timestamp before it enters state.

Types

type Config

type Config struct {
	Mode      Mode
	Heuristic HeuristicConfig
	Remote    *RemoteConfig
}

func DecodeConfig

func DecodeConfig(input yaml.Node) (Config, error)

DecodeConfig strictly decodes the feature-owned config subtree. Registration enablement belongs to the outer plugins.features entry and is not duplicated here.

type HeuristicConfig

type HeuristicConfig struct {
	IgnoredUserAgentPrefixes []string
}

type Key

type Key struct {
	Kind ScopeKind
	ID   string
}

Key scopes feature state to one proxy-owned secure session or A-leg. ScopeKind is part of the key so equal ID bytes from different authorities do not share state.

func ResolveKey

func ResolveKey(view session.SessionView) (Key, error)

ResolveKey prefers the proxy-owned secure session ID and falls back to the proxy-owned A-leg only when the secure session ID is exactly empty. It never reads ClientSessionHint and never rewrites an authoritative ID.

type LocalDecision

type LocalDecision struct {
	Promotes     bool
	Preserves    bool
	Source       session.ClassificationSource
	EvidenceCode session.EvidenceCode
	ClientFamily agentfacts.Family
}

LocalDecision contains bounded policy facts without manufacturing persisted classification state or a revision.

func EvaluateLocal

func EvaluateLocal(cfg Config, input sdkclassification.Input) LocalDecision

EvaluateLocal evaluates accepted client identity, canonical tool categories, and the bounded recognized marker snapshot. It never reads transcript, model, route, workspace root, or raw tool-name data.

type Mode

type Mode string
const (
	ModeHeuristic Mode = "heuristic"
	ModeJev       Mode = "jev"
	ModeHybrid    Mode = "hybrid"
)

type Record

type Record struct {
	Key                  Key
	Classification       session.Classification
	RemoteAttempts       uint32
	RemoteLeaseID        string
	RemoteLeaseUntil     time.Time
	RemoteNextEligibleAt time.Time
	UpdatedAt            time.Time
}

Record is the bounded persisted feature state for one authority key. It contains classification and remote-control metadata only.

type RemoteClaim

type RemoteClaim struct {
	Key          Key
	LeaseID      string
	Attempt      uint32
	RetryBackoff time.Duration
}

RemoteClaim proves ownership of one leased remote attempt. RetryBackoff is captured with the claim so completion can start backoff at completion time; abandoned claims become eligible again as soon as their lease expires.

type RemoteCompletion

type RemoteCompletion struct {
	Proposal session.Classification
}

RemoteCompletion carries only a validated positive proposal. The zero value represents a below-threshold, unavailable, or otherwise non-positive result.

type RemoteConfig

type RemoteConfig struct {
	Provider              string
	APIKeyEnv             string
	Timeout               time.Duration
	MaxAttemptsPerSession int
	LeaseTTL              time.Duration
	RetryBackoff          time.Duration
	PositiveThreshold     float64
}

type ScopeKind

type ScopeKind string

ScopeKind identifies which proxy-owned authority issued an opaque ID.

const (
	ScopeSecureSession ScopeKind = "secure_session"
	ScopeALeg          ScopeKind = "a_leg"
)

type Store

type Store interface {
	Load(ctx context.Context, key Key) (Record, bool, error)

	Promote(ctx context.Context, key Key, proposal session.Classification, now time.Time) (record Record, promoted bool, err error)

	ClaimRemote(ctx context.Context, key Key, now time.Time, maxAttempts uint32, leaseTTL time.Duration, retryBackoff time.Duration) (claim RemoteClaim, record Record, ok bool, err error)

	CompleteRemote(ctx context.Context, claim RemoteClaim, result RemoteCompletion, now time.Time) (Record, error)
}

Store is the consumed feature-owned persistence contract. Implementations must preserve first-positive-wins semantics and make remote lease operations atomic for each authority key.

Directories

Path Synopsis
Package testfixtures exposes the shared, data-driven evidence matrix used by session-classification acceptance tests.
Package testfixtures exposes the shared, data-driven evidence matrix used by session-classification acceptance tests.

Jump to

Keyboard shortcuts

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