cache

package
v8.0.51 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// AntigravityReasoningReplayCacheTTL limits how long encrypted reasoning replay
	// items stay in process memory.
	AntigravityReasoningReplayCacheTTL = 1 * time.Hour

	// AntigravityReasoningReplayCacheMaxEntries bounds process memory for replay
	// continuity. Oldest entries are evicted first.
	AntigravityReasoningReplayCacheMaxEntries = 10240

	// AntigravityReasoningReplayCacheEvictBatchSize leaves headroom after the cache
	// reaches capacity so high write volume does not rescan the map every turn.
	AntigravityReasoningReplayCacheEvictBatchSize = 128

	// AntigravityReasoningReplayCacheMaxItemsPerEntry and MaxBytesPerEntry
	// bound one logical conversation. Oversized chains are not partially cached,
	// because dropping an arbitrary prefix would break native signature ordering.
	AntigravityReasoningReplayCacheMaxItemsPerEntry = 4096
	AntigravityReasoningReplayCacheMaxBytesPerEntry = 16 << 20
)
View Source
const (
	// ClaudeThinkingReplayCacheTTL limits how long signed assistant turns stay replayable.
	ClaudeThinkingReplayCacheTTL = 1 * time.Hour

	// ClaudeThinkingReplayCacheMaxEntries bounds process memory used by Claude replay continuity.
	ClaudeThinkingReplayCacheMaxEntries = 10240

	// ClaudeThinkingReplayCacheEvictBatchSize leaves headroom after reaching capacity.
	ClaudeThinkingReplayCacheEvictBatchSize = 128

	// ClaudeThinkingReplayCacheMaxBytesPerSession bounds all cached assistant turns for one session.
	ClaudeThinkingReplayCacheMaxBytesPerSession = 8 << 20

	// ClaudeThinkingReplayCacheMaxTurnsPerSession bounds the number of assistant turns per session.
	ClaudeThinkingReplayCacheMaxTurnsPerSession = 64

	// ClaudeThinkingReplayCacheMaxBlocksPerTurn prevents pathological content arrays.
	ClaudeThinkingReplayCacheMaxBlocksPerTurn = 512

	// ClaudeThinkingReplayCacheMaxTotalBytes bounds aggregate in-process Claude replay content.
	ClaudeThinkingReplayCacheMaxTotalBytes = 256 << 20
)
View Source
const (
	// CodexReasoningReplayTurnType identifies an internal turn-boundary marker.
	CodexReasoningReplayTurnType = "cpa_codex_replay_turn"

	// CodexReasoningReplayCacheTTL limits how long encrypted reasoning replay
	// items stay in process memory.
	CodexReasoningReplayCacheTTL = 1 * time.Hour

	// CodexReasoningReplayCacheMaxEntries bounds process memory for replay
	// continuity. Oldest entries are evicted first.
	CodexReasoningReplayCacheMaxEntries = 10240

	// CodexReasoningReplayCacheMaxTurnsPerEntry bounds cumulative state for one agent.
	CodexReasoningReplayCacheMaxTurnsPerEntry = 256

	// CodexReasoningReplayCacheMaxBytesPerEntry bounds cumulative serialized items for one agent.
	CodexReasoningReplayCacheMaxBytesPerEntry = 16 << 20

	// CodexReasoningReplayCacheEvictBatchSize leaves headroom after the cache
	// reaches capacity so high write volume does not rescan the map every turn.
	CodexReasoningReplayCacheEvictBatchSize = 128
)
View Source
const (
	// KimiThinkingReplayCacheTTL limits how long signed assistant content stays replayable.
	KimiThinkingReplayCacheTTL = 1 * time.Hour

	// KimiThinkingReplayCacheMaxEntries bounds process memory used for replay continuity.
	KimiThinkingReplayCacheMaxEntries = 10240

	// KimiThinkingReplayCacheEvictBatchSize leaves headroom after reaching capacity.
	KimiThinkingReplayCacheEvictBatchSize = 128

	// KimiThinkingReplayCacheMaxBytesPerEntry bounds one complete assistant content array.
	KimiThinkingReplayCacheMaxBytesPerEntry = 8 << 20

	// KimiThinkingReplayCacheMaxBlocksPerEntry prevents pathological content arrays.
	KimiThinkingReplayCacheMaxBlocksPerEntry = 512

	// KimiThinkingReplayCacheMaxTotalBytes bounds aggregate in-process replay content.
	KimiThinkingReplayCacheMaxTotalBytes = 256 << 20
)
View Source
const (
	// SignatureCacheTTL is how long signatures are valid
	SignatureCacheTTL = 3 * time.Hour

	// SignatureTextHashLen is the length of the hash key (16 hex chars = 64-bit key space)
	SignatureTextHashLen = 16

	// MinValidSignatureLen is the minimum length for a signature to be considered valid
	MinValidSignatureLen = 50

	// CacheCleanupInterval controls how often stale entries are purged
	CacheCleanupInterval = 10 * time.Minute
)
View Source
const (
	// XAIReasoningReplayCacheTTL limits how long encrypted reasoning replay
	// items stay in process memory.
	XAIReasoningReplayCacheTTL = 1 * time.Hour

	// XAIReasoningReplayCacheMaxEntries bounds process memory for replay
	// continuity. Oldest entries are evicted first.
	XAIReasoningReplayCacheMaxEntries = 10240

	// XAIReasoningReplayCacheEvictBatchSize leaves headroom after the cache
	// reaches capacity so high write volume does not rescan the map every turn.
	XAIReasoningReplayCacheEvictBatchSize = 128
)

Variables

This section is empty.

Functions

func AppendCodexReasoningReplayItemsBestEffort

func AppendCodexReasoningReplayItemsBestEffort(ctx context.Context, modelName, sessionKey string, items [][]byte) bool

AppendCodexReasoningReplayItemsBestEffort appends one completed turn to existing replay state.

func CacheAntigravityReasoningReplayItem

func CacheAntigravityReasoningReplayItem(modelName, sessionKey string, item []byte) bool

CacheAntigravityReasoningReplayItem stores a final GPT/Codex reasoning item for stateless replay. The stored item is normalized to the minimal shape accepted by Responses input replay.

func CacheAntigravityReasoningReplayItems

func CacheAntigravityReasoningReplayItems(modelName, sessionKey string, items [][]byte) bool

CacheAntigravityReasoningReplayItems stores the final GPT/Codex assistant output items needed to replay a stateless next turn.

func CacheAntigravityReasoningReplayItemsBestEffort

func CacheAntigravityReasoningReplayItemsBestEffort(ctx context.Context, modelName, sessionKey string, items [][]byte) bool

CacheAntigravityReasoningReplayItemsBestEffort stores replay items for completed response paths.

func CacheClaudeThinkingReplayBestEffort

func CacheClaudeThinkingReplayBestEffort(ctx context.Context, modelFamily, sessionKey string, content []byte) bool

CacheClaudeThinkingReplayBestEffort stores one complete signed assistant content array.

func CacheClaudeWebSearchResult added in v8.0.34

func CacheClaudeWebSearchResult(sessionKey, toolUseID string, content []byte, ttl time.Duration, limit int)

CacheClaudeWebSearchResult stores the raw content of one web_search_tool_result block for a session. Memory is bounded by the maximum entry count (limit); least recently used entries are evicted when the entry limit is exceeded.

func CacheClaudeWebSearchResultBestEffort added in v8.0.35

func CacheClaudeWebSearchResultBestEffort(ctx context.Context, sessionKey, toolUseID string, content []byte, ttl time.Duration, limit int) bool

CacheClaudeWebSearchResultBestEffort stores the raw content of one web_search_tool_result block for completed response paths.

func CacheCodexReasoningReplayItem

func CacheCodexReasoningReplayItem(modelName, sessionKey string, item []byte) bool

CacheCodexReasoningReplayItem stores a final GPT/Codex reasoning item for stateless replay. The stored item is normalized to the minimal shape accepted by Responses input replay.

func CacheCodexReasoningReplayItems

func CacheCodexReasoningReplayItems(modelName, sessionKey string, items [][]byte) bool

CacheCodexReasoningReplayItems stores the final GPT/Codex assistant output items needed to replay a stateless next turn.

func CacheCodexReasoningReplayItemsBestEffort

func CacheCodexReasoningReplayItemsBestEffort(ctx context.Context, modelName, sessionKey string, items [][]byte) bool

CacheCodexReasoningReplayItemsBestEffort stores replay items for completed response paths.

func CacheKimiThinkingReplayBestEffort

func CacheKimiThinkingReplayBestEffort(ctx context.Context, modelFamily, sessionKey string, content []byte) bool

CacheKimiThinkingReplayBestEffort stores one complete signed assistant content array.

func CacheSignature

func CacheSignature(modelName, text, signature string)

CacheSignature stores a thinking signature for a given model group and text. Used for Claude models that require signed thinking blocks in multi-turn conversations.

func CacheSignatureBestEffort

func CacheSignatureBestEffort(ctx context.Context, modelName, text, signature string) bool

CacheSignatureBestEffort stores a thinking signature for completed response paths.

func CacheXAIReasoningReplayItem

func CacheXAIReasoningReplayItem(modelName, sessionKey string, item []byte) bool

CacheXAIReasoningReplayItem stores a final Grok reasoning item for stateless replay. The stored item is normalized to the minimal shape accepted by Responses input replay.

func CacheXAIReasoningReplayItems

func CacheXAIReasoningReplayItems(modelName, sessionKey string, items [][]byte) bool

CacheXAIReasoningReplayItems stores the final Grok assistant output items needed to replay a stateless next turn.

func CacheXAIReasoningReplayItemsBestEffort

func CacheXAIReasoningReplayItemsBestEffort(ctx context.Context, modelName, sessionKey string, items [][]byte) bool

CacheXAIReasoningReplayItemsBestEffort stores replay items for completed response paths.

func ClearAntigravityReasoningReplayCache

func ClearAntigravityReasoningReplayCache()

ClearAntigravityReasoningReplayCache clears all Antigravity reasoning replay state.

func ClearClaudeThinkingReplayCache

func ClearClaudeThinkingReplayCache()

ClearClaudeThinkingReplayCache clears only Claude replay state.

func ClearClaudeWebSearchResultCache added in v8.0.34

func ClearClaudeWebSearchResultCache()

ClearClaudeWebSearchResultCache removes every stored entry.

func ClearCodexReasoningReplayCache

func ClearCodexReasoningReplayCache()

ClearCodexReasoningReplayCache clears all Codex reasoning replay state.

func ClearKimiThinkingReplayCache

func ClearKimiThinkingReplayCache()

ClearKimiThinkingReplayCache clears all in-process Kimi replay state.

func ClearSignatureCache

func ClearSignatureCache(modelName string)

ClearSignatureCache clears signature cache for a specific model group or all groups.

func ClearXAIReasoningReplayCache

func ClearXAIReasoningReplayCache()

ClearXAIReasoningReplayCache clears all xAI reasoning replay state.

func DeleteAntigravityReasoningReplayItem

func DeleteAntigravityReasoningReplayItem(modelName, sessionKey string)

DeleteAntigravityReasoningReplayItem removes one replay item after upstream rejects it or the caller otherwise knows it is stale.

func DeleteAntigravityReasoningReplayItemRequired

func DeleteAntigravityReasoningReplayItemRequired(ctx context.Context, modelName, sessionKey string) error

DeleteAntigravityReasoningReplayItemRequired removes one replay item for request-time paths.

func DeleteAntigravityReasoningReplayItemsIfUnchanged

func DeleteAntigravityReasoningReplayItemsIfUnchanged(ctx context.Context, modelName, sessionKey string, snapshot AntigravityReasoningReplaySnapshot) (bool, error)

DeleteAntigravityReasoningReplayItemsIfUnchanged clears replay state only when it still matches the state read for this request.

func DeleteCachedSignatureRequired

func DeleteCachedSignatureRequired(ctx context.Context, modelName, text string) error

DeleteCachedSignatureRequired removes one exact cached signature.

func DeleteClaudeThinkingReplayIfUnchanged

func DeleteClaudeThinkingReplayIfUnchanged(ctx context.Context, modelFamily, sessionKey string, snapshot ClaudeThinkingReplaySnapshot) (bool, error)

DeleteClaudeThinkingReplayIfUnchanged clears replay state only if the request snapshot is current.

func DeleteClaudeThinkingReplayRequired

func DeleteClaudeThinkingReplayRequired(ctx context.Context, modelFamily, sessionKey string) error

DeleteClaudeThinkingReplayRequired removes stale replay state unconditionally.

func DeleteCodexReasoningReplayItem

func DeleteCodexReasoningReplayItem(modelName, sessionKey string)

DeleteCodexReasoningReplayItem removes one replay item after upstream rejects it or the caller otherwise knows it is stale.

func DeleteCodexReasoningReplayItemRequired

func DeleteCodexReasoningReplayItemRequired(ctx context.Context, modelName, sessionKey string) error

DeleteCodexReasoningReplayItemRequired removes one replay item for request-time paths.

func DeleteKimiThinkingReplayIfUnchanged

func DeleteKimiThinkingReplayIfUnchanged(ctx context.Context, modelFamily, sessionKey string, snapshot KimiThinkingReplaySnapshot) (bool, error)

DeleteKimiThinkingReplayIfUnchanged clears replay state only if the request snapshot is current.

func DeleteKimiThinkingReplayRequired

func DeleteKimiThinkingReplayRequired(ctx context.Context, modelFamily, sessionKey string) error

DeleteKimiThinkingReplayRequired removes stale replay state unconditionally.

func DeleteXAIReasoningReplayItem

func DeleteXAIReasoningReplayItem(modelName, sessionKey string)

DeleteXAIReasoningReplayItem removes one replay item after upstream rejects it or the caller otherwise knows it is stale.

func DeleteXAIReasoningReplayItemRequired

func DeleteXAIReasoningReplayItemRequired(ctx context.Context, modelName, sessionKey string) error

DeleteXAIReasoningReplayItemRequired removes one replay item for request-time paths.

func GetAntigravityReasoningReplayItem

func GetAntigravityReasoningReplayItem(modelName, sessionKey string) ([]byte, bool)

GetAntigravityReasoningReplayItem retrieves a normalized reasoning replay item.

func GetAntigravityReasoningReplayItems

func GetAntigravityReasoningReplayItems(modelName, sessionKey string) ([][]byte, bool)

GetAntigravityReasoningReplayItems retrieves normalized assistant output items.

func GetAntigravityReasoningReplayItemsRequired

func GetAntigravityReasoningReplayItemsRequired(ctx context.Context, modelName, sessionKey string) ([][]byte, bool, error)

GetAntigravityReasoningReplayItemsRequired retrieves replay items for request-time paths.

func GetCachedSignature

func GetCachedSignature(modelName, text string) string

GetCachedSignature retrieves a cached signature for a given model group and text. Returns empty string if not found or expired.

func GetCachedSignatureRequired

func GetCachedSignatureRequired(ctx context.Context, modelName, text string) (string, error)

GetCachedSignatureRequired retrieves a cached signature for request-time paths.

func GetClaudeThinkingReplayRequired

func GetClaudeThinkingReplayRequired(ctx context.Context, modelFamily, sessionKey string) ([][]byte, bool, error)

GetClaudeThinkingReplayRequired retrieves all cached assistant turns for request-time replay.

func GetClaudeWebSearchResult added in v8.0.34

func GetClaudeWebSearchResult(sessionKey, toolUseID string, ttl ...time.Duration) ([]byte, bool)

GetClaudeWebSearchResult returns a copy of the stored content and extends its lifetime. Expired entries are removed and reported as missing.

func GetClaudeWebSearchResultRequired added in v8.0.35

func GetClaudeWebSearchResultRequired(ctx context.Context, sessionKey, toolUseID string, ttl ...time.Duration) ([]byte, bool, error)

GetClaudeWebSearchResultRequired retrieves a copy of the stored content for request-time paths and extends its lifetime.

func GetCodexReasoningReplayItem

func GetCodexReasoningReplayItem(modelName, sessionKey string) ([]byte, bool)

GetCodexReasoningReplayItem retrieves the first normalized upstream replay item.

func GetCodexReasoningReplayItems

func GetCodexReasoningReplayItems(modelName, sessionKey string) ([][]byte, bool)

GetCodexReasoningReplayItems retrieves normalized assistant output items.

func GetCodexReasoningReplayItemsRequired

func GetCodexReasoningReplayItemsRequired(ctx context.Context, modelName, sessionKey string) ([][]byte, bool, error)

GetCodexReasoningReplayItemsRequired retrieves replay items for request-time paths.

func GetKimiThinkingReplayRequired

func GetKimiThinkingReplayRequired(ctx context.Context, modelFamily, sessionKey string) ([]byte, bool, error)

GetKimiThinkingReplayRequired retrieves complete assistant content for request-time replay.

func GetModelGroup

func GetModelGroup(modelName string) string

func GetXAIReasoningReplayItem

func GetXAIReasoningReplayItem(modelName, sessionKey string) ([]byte, bool)

GetXAIReasoningReplayItem retrieves a normalized reasoning replay item.

func GetXAIReasoningReplayItems

func GetXAIReasoningReplayItems(modelName, sessionKey string) ([][]byte, bool)

GetXAIReasoningReplayItems retrieves normalized assistant output items.

func GetXAIReasoningReplayItemsRequired

func GetXAIReasoningReplayItemsRequired(ctx context.Context, modelName, sessionKey string) ([][]byte, bool, error)

GetXAIReasoningReplayItemsRequired retrieves replay items for request-time paths.

func HasValidSignature

func HasValidSignature(modelName, signature string) bool

HasValidSignature checks if a signature is valid (non-empty and long enough)

func InteractionsCallKey added in v8.0.14

func InteractionsCallKey(ids []string) string

InteractionsCallKey rejects ambiguous or incomplete call sets.

func ReplaceAntigravityReasoningReplayItemsIfUnchanged

func ReplaceAntigravityReasoningReplayItemsIfUnchanged(ctx context.Context, modelName, sessionKey string, snapshot AntigravityReasoningReplaySnapshot, items [][]byte) (bool, error)

ReplaceAntigravityReasoningReplayItemsIfUnchanged publishes a completed chain only when no newer request has changed the state read by this request.

func ReplaceClaudeThinkingReplayIfUnchanged

func ReplaceClaudeThinkingReplayIfUnchanged(ctx context.Context, modelFamily, sessionKey string, snapshot ClaudeThinkingReplaySnapshot, content []byte) (bool, error)

ReplaceClaudeThinkingReplayIfUnchanged appends a completed assistant turn only if the request snapshot is current.

func ReplaceKimiThinkingReplayIfUnchanged

func ReplaceKimiThinkingReplayIfUnchanged(ctx context.Context, modelFamily, sessionKey string, snapshot KimiThinkingReplaySnapshot, content []byte) (bool, error)

ReplaceKimiThinkingReplayIfUnchanged stores completed content only if the request snapshot is current.

func SetSignatureBypassStrictMode

func SetSignatureBypassStrictMode(strict bool)

SetSignatureBypassStrictMode controls whether bypass mode uses strict protobuf-tree validation.

func SetSignatureCacheEnabled

func SetSignatureCacheEnabled(enabled bool)

SetSignatureCacheEnabled switches Antigravity signature handling between cache mode and bypass mode.

func SignatureBypassStrictMode

func SignatureBypassStrictMode() bool

SignatureBypassStrictMode returns whether bypass mode uses strict protobuf-tree validation.

func SignatureCacheEnabled

func SignatureCacheEnabled() bool

SignatureCacheEnabled returns whether signature cache validation is enabled.

Types

type AntigravityReasoningReplaySnapshot

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

AntigravityReasoningReplaySnapshot identifies the exact replay state read for one request. Its fields are intentionally opaque outside this package.

func GetAntigravityReasoningReplayItemsWithSnapshotRequired

func GetAntigravityReasoningReplayItemsWithSnapshotRequired(ctx context.Context, modelName, sessionKey string) ([][]byte, AntigravityReasoningReplaySnapshot, bool, error)

GetAntigravityReasoningReplayItemsWithSnapshotRequired retrieves replay items and the exact cache state that guarded this request.

type BoundedLRU

type BoundedLRU[K comparable, V any] struct {
	// contains filtered or unexported fields
}

BoundedLRU stores at most capacity values and evicts the least recently used value when a new key crosses the bound. The optional eviction callback runs after the cache lock is released.

func NewBoundedLRU

func NewBoundedLRU[K comparable, V any](capacity int, onEvict func(K, V)) *BoundedLRU[K, V]

func (*BoundedLRU[K, V]) Delete

func (cache *BoundedLRU[K, V]) Delete(key K) bool

func (*BoundedLRU[K, V]) Get

func (cache *BoundedLRU[K, V]) Get(key K) (V, bool)

func (*BoundedLRU[K, V]) GetOrAdd

func (cache *BoundedLRU[K, V]) GetOrAdd(key K, create func() V) V

GetOrAdd returns the cached value or creates and stores one while holding the cache lock. The create function must not call back into this cache.

func (*BoundedLRU[K, V]) Len

func (cache *BoundedLRU[K, V]) Len() int

type ClaudeThinkingReplaySnapshot

type ClaudeThinkingReplaySnapshot = KimiThinkingReplaySnapshot

ClaudeThinkingReplaySnapshot identifies the exact replay generation read for one request.

func GetClaudeThinkingReplayWithSnapshotRequired

func GetClaudeThinkingReplayWithSnapshotRequired(ctx context.Context, modelFamily, sessionKey string) ([][]byte, ClaudeThinkingReplaySnapshot, bool, error)

GetClaudeThinkingReplayWithSnapshotRequired retrieves replay content and the exact cache state read.

type InteractionsContinuation added in v8.0.14

type InteractionsContinuation struct {
	ID          string
	Environment string
}

InteractionsContinuation contains only upstream continuation identifiers.

type InteractionsSessionCache added in v8.0.14

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

InteractionsSessionCache is a bounded, process-local cache. Keys must already isolate the caller, credential, model, conversation, and pending call IDs.

func NewInteractionsSessionCache added in v8.0.14

func NewInteractionsSessionCache() *InteractionsSessionCache

func (*InteractionsSessionCache) Get added in v8.0.14

func (*InteractionsSessionCache) Put added in v8.0.14

type KimiThinkingReplaySnapshot

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

KimiThinkingReplaySnapshot identifies the exact replay generation read for one request.

func GetKimiThinkingReplayWithSnapshotRequired

func GetKimiThinkingReplayWithSnapshotRequired(ctx context.Context, modelFamily, sessionKey string) ([]byte, KimiThinkingReplaySnapshot, bool, error)

GetKimiThinkingReplayWithSnapshotRequired retrieves replay content and the exact cache state read.

type SignatureEntry

type SignatureEntry struct {
	Signature string
	Timestamp time.Time
}

SignatureEntry holds a cached thinking signature with timestamp

type XAIReasoningReplayStoreStatus

type XAIReasoningReplayStoreStatus int

XAIReasoningReplayStoreStatus reports why a completed-turn cache write succeeded or failed so callers can decide whether to keep prior entries.

const (
	// XAIReasoningReplayStoreInvalidArgs means model/session were empty.
	XAIReasoningReplayStoreInvalidArgs XAIReasoningReplayStoreStatus = iota
	// XAIReasoningReplayStored means a valid reasoning batch was written.
	XAIReasoningReplayStored
	// XAIReasoningReplayNoReplayableState means the completed output had no
	// cacheable reasoning batch (for example reasoning disabled).
	XAIReasoningReplayNoReplayableState
	// XAIReasoningReplayStoreBackendError means normalize succeeded but the
	// storage backend failed; previous entries should be retained.
	XAIReasoningReplayStoreBackendError
)

func StoreXAIReasoningReplayItems

func StoreXAIReasoningReplayItems(ctx context.Context, modelName, sessionKey string, items [][]byte) XAIReasoningReplayStoreStatus

StoreXAIReasoningReplayItems stores replay items and distinguishes empty completed state from backend failures.

Jump to

Keyboard shortcuts

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