helps

package
v7.2.147 Latest Latest
Warning

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

Go to latest
Published: Sep 1, 2026 License: MIT Imports: 67 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ClaudeCodeSessionHeader = "X-Claude-Code-Session-Id"
	ClaudeCodeAgentHeader   = "X-Claude-Code-Agent-Id"
	ClaudeCodeMainAgentID   = "main"
)
View Source
const DefaultTransportCacheCapacity = 64

DefaultTransportCacheCapacity bounds how many transports a TransportCache keeps alive at once. Every cached transport owns an independent connection pool, so an unbounded cache would let idle sockets and the goroutines managing them grow without limit whenever keys churn, for example when a credential's proxy is rotated through the management API or when an SDK embedder supplies a freshly built base transport per request.

Variables

View Source
var (
	ClaudeDeviceProfileBeforeCandidateStore func(ClaudeDeviceProfile)
)

Functions

func APIKeyFromContext

func APIKeyFromContext(ctx context.Context) string

func APIKeyModelIsCompat added in v7.2.121

func APIKeyModelIsCompat(req cliproxyexecutor.Request) bool

APIKeyModelIsCompat reports whether the selected API-key model enables compatibility handling for Claude thinking blocks.

func AllocateClaudeMCPToolAlias added in v7.2.132

func AllocateClaudeMCPToolAlias(secret, original string, reserved map[string]bool) (string, bool)

AllocateClaudeMCPToolAlias picks an alias that is not already reserved. Attempts are capped at the wordlist size so names that sanitize to the same suffix cannot spin forever. ok is false only when every one-word tool ID for this semantic is already reserved.

func AppendAPIResponseChunk

func AppendAPIResponseChunk(ctx context.Context, cfg *config.Config, chunk []byte)

AppendAPIResponseChunk appends an upstream response chunk to Gin context for request logging.

func AppendAPIWebsocketResponse

func AppendAPIWebsocketResponse(ctx context.Context, cfg *config.Config, payload []byte)

AppendAPIWebsocketResponse stores an upstream websocket response frame in Gin context.

func AppendCodexAPIWebsocketResponse added in v7.2.142

func AppendCodexAPIWebsocketResponse(ctx context.Context, cfg *config.Config, payload []byte)

AppendCodexAPIWebsocketResponse stores a codex upstream websocket response frame and merges any quota event headers carried by the frame into the request log.

func ApplyClaudeCredentialMetadata added in v7.2.116

func ApplyClaudeCredentialMetadata(payload []byte, auth *cliproxyauth.Auth, sessionID string) ([]byte, string, error)

ApplyClaudeCredentialMetadata rewrites the identity exception shared by native and cloaked OAuth requests.

func ApplyClaudeDefaultDeviceProfileHeaders added in v7.2.116

func ApplyClaudeDefaultDeviceProfileHeaders(r *http.Request, cfg *config.Config)

func ApplyClaudeDeviceProfileHeaders

func ApplyClaudeDeviceProfileHeaders(r *http.Request, profile ClaudeDeviceProfile)

func ApplyClaudeLegacyDeviceHeaders

func ApplyClaudeLegacyDeviceHeaders(r *http.Request, ginHeaders http.Header, cfg *config.Config, confirmedClaudeCode bool)

func ApplyPayloadConfigWithRequest added in v7.1.8

func ApplyPayloadConfigWithRequest(cfg *config.Config, model, protocol, fromProtocol, root string, payload, original []byte, requestedModel string, requestPath string, headers http.Header) []byte

ApplyPayloadConfigWithRequest applies payload config using source protocol and request header gates.

func ApplyPayloadConfigWithRequestTracked added in v7.2.120

func ApplyPayloadConfigWithRequestTracked(cfg *config.Config, model, protocol, fromProtocol, root string, payload, original []byte, requestedModel string, requestPath string, headers http.Header, trackedPath string) ([]byte, bool)

ApplyPayloadConfigWithRequestTracked applies payload config and reports whether an applied rule targeted trackedPath or one of its descendants.

func ApplyPayloadConfigWithRoot

func ApplyPayloadConfigWithRoot(cfg *config.Config, model, protocol, root string, payload, original []byte, requestedModel string, requestPath string) []byte

ApplyPayloadConfigWithRoot behaves like applyPayloadConfig but treats all parameter paths as relative to the provided root path and restricts matches to the given protocol when supplied. Defaults are checked against the original payload when provided. requestedModel carries the client-visible model name before alias resolution so payload rules can target aliases precisely. requestPath is the inbound HTTP request path (when available) used for endpoint-scoped gates.

func ApplyRequestThinking added in v7.2.105

func ApplyRequestThinking(body []byte, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, fromFormat, toFormat, provider string) ([]byte, error)

ApplyRequestThinking preserves the registry lookup path unless the auth manager bound an exact configured API-key model definition to this attempt.

func ApplyThinkingWithSourcePayload added in v7.2.112

func ApplyThinkingWithSourcePayload(body, currentSourcePayload, originalSourcePayload []byte, model, fromFormat, toFormat, providerKey string) ([]byte, error)

ApplyThinkingWithSourcePayload preserves summary visibility from the original client payload while applying thinking configuration to its translated target payload. currentSourcePayload is the payload that was translated, while originalSourcePayload retains intent removed by an earlier interceptor.

func AugmentClaudeBuiltinToolRegistry

func AugmentClaudeBuiltinToolRegistry(body []byte, registry map[string]bool) map[string]bool

func BeginClaudeDiagnostics added in v7.2.116

func BeginClaudeDiagnostics(credentialIdentity, sessionID string) (key string, sequence uint64, previousMessageID string)

BeginClaudeDiagnostics starts one request generation for a stable credential identity and Claude conversation. It returns the last successfully completed upstream message ID, if any. Only a SHA-256 digest of the credential identity and session is retained as the cache key, so access-token rotation does not interrupt continuity.

func BuildOpenAIUsageJSON

func BuildOpenAIUsageJSON(count int64) []byte

BuildOpenAIUsageJSON returns a minimal usage structure understood by downstream translators.

func CachedSessionID

func CachedSessionID(apiKey string) string

CachedSessionID returns a stable session UUID per apiKey, refreshing the TTL on each access.

func CachedSessionIDRequired added in v7.2.0

func CachedSessionIDRequired(ctx context.Context, apiKey string) (string, error)

CachedSessionIDRequired returns a stable session UUID per apiKey for request-time paths.

func CachedUserID

func CachedUserID(apiKey string) string

func CachedUserIDRequired added in v7.2.0

func CachedUserIDRequired(ctx context.Context, apiKey string) (string, error)

CachedUserIDRequired returns a stable fake user ID per apiKey for request-time paths.

func ClaudeAgentSessionUUID added in v7.2.116

func ClaudeAgentSessionUUID(headers http.Header, originalPayload, translatedPayload []byte, metadataSets ...map[string]any) string

ClaudeAgentSessionUUID maps the downstream agent conversation to one stable UUID, preserving native Claude Code session signals.

func ClaudeAgentSessionUUIDForRequest added in v7.2.116

func ClaudeAgentSessionUUIDForRequest(headers http.Header, originalPayload, translatedPayload []byte, confirmedClaudeCode bool, metadataSets ...map[string]any) string

ClaudeAgentSessionUUIDForRequest preserves Claude-specific session signals only for a confirmed native caller. Other callers use protocol session fields, execution metadata, or the stable derived conversation root.

func ClaudeCLIAuthIdentitySeed added in v7.2.136

func ClaudeCLIAuthIdentitySeed(auth *cliproxyauth.Auth) string

ClaudeCLIAuthIdentitySeed returns a stable credential identity that does not rotate with delegated-provider access tokens.

func ClaudeCodeExecutionScope added in v7.2.85

func ClaudeCodeExecutionScope(ctx context.Context, payload []byte, headers http.Header) (string, bool)

ClaudeCodeExecutionScope returns the stable root-session and agent identity used by Codex execution state.

func ClaudeCredentialAccountUUID added in v7.2.116

func ClaudeCredentialAccountUUID(auth *cliproxyauth.Auth) string

ClaudeCredentialAccountUUID returns the selected upstream credential's account UUID.

func ClaudeDeviceProfileStabilizationEnabled

func ClaudeDeviceProfileStabilizationEnabled(cfg *config.Config) bool

func ClaudeHeadersIndicateUnifiedRateLimitRejection added in v7.2.133

func ClaudeHeadersIndicateUnifiedRateLimitRejection(headers http.Header) bool

ClaudeHeadersIndicateUnifiedRateLimitRejection reports whether response headers explicitly declare an Anthropic shared 5h or 7d rate-limit rejection. A Fable-only 7d_oi rejection remains model-scoped when both shared windows are explicitly allowed (status "allowed" or "allowed_warning").

func ClaudeMCPAliasWordCount added in v7.2.132

func ClaudeMCPAliasWordCount() int

ClaudeMCPAliasWordCount is the BIP-39 English dictionary size used for the virtual server pair and the one-word tool ID.

func ClaudeMCPToolAlias added in v7.2.116

func ClaudeMCPToolAlias(secret, original string, attempt uint32) string

ClaudeMCPToolAlias derives a Claude Code-style MCP tool name. Aliases from one caller share a virtual server component. The tool component combines a stable keyed ID with a truncated semantic suffix so the model can distinguish tools by name while the request-local symbol table restores the exact original. A higher attempt linearly probes the next word when a collision must be avoided. Server and tool IDs use BIP-39 English words so weak models are less likely to drift high-entropy Base32 fragments.

func CodexPromptCacheKey added in v7.2.0

func CodexPromptCacheKey(modelName string, userScope string) string

CodexPromptCacheKey builds the Home KV key for a model/user prompt cache.

func CommitClaudeDiagnostics added in v7.2.116

func CommitClaudeDiagnostics(key string, sequence uint64, messageID string)

CommitClaudeDiagnostics advances continuity only after a response completes. A response from an older concurrently-started request cannot overwrite a newer committed generation, including after TTL expiry or capacity eviction.

func CountClaudeInputTokens added in v7.2.102

func CountClaudeInputTokens(payload []byte) (int64, error)

CountClaudeInputTokens estimates tokens for a Claude request with the O200kBase tokenizer.

func CountOpenAIChatTokens

func CountOpenAIChatTokens(enc tokenizer.Codec, payload []byte) (int64, error)

CountOpenAIChatTokens approximates prompt tokens for OpenAI chat completions payloads.

func CreditsUsed

func CreditsUsed(ctx context.Context) bool

CreditsUsed returns true if the request used AI credits.

func DefaultClaudeVersion

func DefaultClaudeVersion(cfg *config.Config) string

DefaultClaudeVersion returns the version string (e.g. "2.1.220") from the current baseline device profile. It extracts the version from the User-Agent.

func DeleteJSONField added in v7.2.20

func DeleteJSONField(body []byte, key string) []byte

DeleteJSONField removes a top-level or nested JSON field from a payload.

func DerivedAntigravitySessionID added in v7.2.101

func DerivedAntigravitySessionID(metadataSets ...map[string]any) string

DerivedAntigravitySessionID maps a derived session identity to Antigravity's negative decimal format.

func DerivedSessionID added in v7.2.101

func DerivedSessionID(metadataSets ...map[string]any) string

DerivedSessionID returns the first context-derived session identity in metadata order.

func DerivedSessionUUID added in v7.2.101

func DerivedSessionUUID(provider string, metadataSets ...map[string]any) string

DerivedSessionUUID maps a derived session identity to a provider-scoped stable UUID.

func EmitWebSocketResponseEvent added in v7.2.143

func EmitWebSocketResponseEvent(ctx context.Context, opts cliproxyexecutor.Options, auth *cliproxyauth.Auth, provider, model string, payload []byte)

EmitWebSocketResponseEvent delivers an upstream WebSocket response frame to any configured observer.

func EnsureClaudeCLIFingerprintIdentity added in v7.2.136

func EnsureClaudeCLIFingerprintIdentity(auth *cliproxyauth.Auth, seed string, synthesizeMissing bool) error

EnsureClaudeCLIFingerprintIdentity prepares auth.Metadata so the shared ApplyClaudeCredentialMetadata path can run.

When synthesizeMissing is false (real OAuth), this is a no-op: missing account or device data must surface as credential errors. When synthesizeMissing is true (fingerprint-profile=claude-code-cli on API keys), missing account_uuid / device pool are filled with stable values derived from seed. Callers that hold a shared Auth must use PrepareClaudeCLIFingerprintAuth instead.

func EnsureClaudeCredentialDevicePoolRequired added in v7.2.116

func EnsureClaudeCredentialDevicePoolRequired(ctx context.Context, auth *cliproxyauth.Auth) ([]string, error)

EnsureClaudeCredentialDevicePoolRequired initializes a credential pool locally, or coordinates it through Home KV when the selected auth is a remote dispatch clone.

func EnsureGeminiLeadingUserContent added in v7.2.137

func EnsureGeminiLeadingUserContent(payload []byte, path string) []byte

EnsureGeminiLeadingUserContent ensures that the contents array at the given path starts with a user turn when sending to Gemini/Antigravity upstreams.

func EnsureResponsesUsageDetails added in v7.2.133

func EnsureResponsesUsageDetails(payload []byte) []byte

EnsureResponsesUsageDetails ensures that Responses usage objects contain output_tokens_details (defaulting reasoning_tokens to 0) and input_tokens_details (defaulting cached_tokens to 0). It supports plain JSON payloads, single-line SSE data: lines, and multi-line SSE frames (e.g. event: ...\ndata: ...).

func ExecutorTypeName added in v7.1.38

func ExecutorTypeName(executor any) string

func ExtractClaudeCodeAgentID added in v7.2.85

func ExtractClaudeCodeAgentID(ctx context.Context, headers http.Header) string

ExtractClaudeCodeAgentID resolves the Claude Code agent ID and uses a stable sentinel for the root agent.

func ExtractClaudeCodeSessionID added in v7.2.30

func ExtractClaudeCodeSessionID(ctx context.Context, payload []byte, headers http.Header) string

ExtractClaudeCodeSessionID resolves a Claude Code session ID, preferring X-Claude-Code-Session-Id over payload metadata.

func ExtractStreamJSONPayload added in v7.2.146

func ExtractStreamJSONPayload(line []byte) []byte

ExtractStreamJSONPayload extracts SSE data/json payload from a raw line.

func FilterSSEUsageMetadata

func FilterSSEUsageMetadata(payload []byte) []byte

FilterSSEUsageMetadata removes usageMetadata from SSE events that are not terminal (finishReason != "stop"). Stop chunks are left untouched. This function is shared between aistudio and antigravity executors.

func GenerateFakeUserID

func GenerateFakeUserID() string

func GenerateFakeUserIDWithSessionID added in v7.2.116

func GenerateFakeUserIDWithSessionID(sessionID string) string

func HasCodexMultiAgentV2NamespaceConflict added in v7.2.130

func HasCodexMultiAgentV2NamespaceConflict(payload []byte) bool

HasCodexMultiAgentV2NamespaceConflict reports whether the request defines the reserved optimized namespace, which must remain untouched.

func HeaderValueCaseInsensitive added in v7.2.137

func HeaderValueCaseInsensitive(headers http.Header, name string) string

HeaderValueCaseInsensitive returns the first non-empty header value matching name case-insensitively.

func IsAnthropicUpstreamURL added in v7.2.116

func IsAnthropicUpstreamURL(u *url.URL) bool

IsAnthropicUpstreamURL reports whether a resolved request targets Anthropic's first-party API origin. Claude-specific body, header, HTTP, and TLS behavior must all use this gate so they cannot drift onto custom ports or userinfo URLs.

func IsChatTokenEvent added in v7.2.146

func IsChatTokenEvent(payload []byte) bool

IsChatTokenEvent reports whether the given OpenAI-compatible Chat Completions SSE or JSON chunk carries substantive output token content (such as text delta, reasoning content, or tool call arguments). It filters out container metadata, role announcements, and empty delta frames.

func IsClaudeMCPToolName added in v7.2.116

func IsClaudeMCPToolName(name string) bool

IsClaudeMCPToolName reports whether name follows Claude Code's MCP tool convention and contains only characters accepted by Anthropic tool names.

func IsClaudeServerToolType added in v7.2.116

func IsClaudeServerToolType(toolType string) bool

IsClaudeServerToolType reports whether a typed declaration is a recognized Anthropic-operated tool. Client-defined type:"custom" declarations are not server tools and must remain eligible for MCP aliasing.

func IsClaudeTokenEvent added in v7.2.146

func IsClaudeTokenEvent(payload []byte) bool

IsClaudeTokenEvent reports whether an Anthropic Messages SSE chunk carries substantive output token content (such as text delta, thinking delta, or tool input delta). It filters out message_start, ping, content_block_stop, and empty containers.

func IsGeminiTokenEvent added in v7.2.146

func IsGeminiTokenEvent(payload []byte) bool

IsGeminiTokenEvent reports whether a Google Gemini / Antigravity streaming chunk carries substantive output token content (such as text parts, thought traces, or function calls). It filters out metadata-only chunks (e.g. standalone usageMetadata) and empty parts.

func IsResponsesTokenEvent added in v7.2.146

func IsResponsesTokenEvent(payload []byte) bool

IsResponsesTokenEvent reports whether the given OpenAI/xAI Responses API WebSocket or SSE event payload carries an actual output token, reasoning trace, tool call argument, or multimodal delta, according to the official Responses API streaming / websocket specification plus Codex-compatible private events.

func IsValidUserID

func IsValidUserID(userID string) bool

func IterateStreamLines added in v7.2.146

func IterateStreamLines(payload []byte, fn func(line []byte))

IterateStreamLines splits payload by newline and invokes fn for non-empty lines.

func JSONPayload

func JSONPayload(line []byte) []byte

func JoinRawJSONArray added in v7.2.92

func JoinRawJSONArray(items [][]byte) []byte

JoinRawJSONArray joins validated raw JSON array items without re-encoding them.

func JoinRawJSONStrings added in v7.2.92

func JoinRawJSONStrings(items []string) []byte

JoinRawJSONStrings joins raw JSON array items held as strings.

func LogWithRequestID

func LogWithRequestID(ctx context.Context) *log.Entry

logWithRequestID returns a logrus Entry with request_id field populated from context. If no request ID is found in context, it returns the standard logger.

func MapStainlessArch

func MapStainlessArch() string

func MapStainlessOS

func MapStainlessOS() string

func MarkCreditsUsed

func MarkCreditsUsed(ctx context.Context)

MarkCreditsUsed flags the request as having used AI credits for billing.

func MergeStreamUsageDetail added in v7.2.146

func MergeStreamUsageDetail(existing, update usage.Detail) usage.Detail

MergeStreamUsageDetail merges existing stream usage with a newer update.

func NewProxyAwareHTTPClient

func NewProxyAwareHTTPClient(ctx context.Context, cfg *config.Config, auth *cliproxyauth.Auth, timeout time.Duration) *http.Client

NewProxyAwareHTTPClient creates an HTTP client with proper proxy configuration priority: 1. Use auth.ProxyURL if configured (highest priority) 2. Use cfg.ProxyURL if auth proxy is not configured 3. Use RoundTripper from context if neither are configured

Parameters:

  • ctx: The context containing optional RoundTripper
  • cfg: The application configuration
  • auth: The authentication information
  • timeout: The client timeout (0 means no timeout)

Returns:

  • *http.Client: An HTTP client with configured proxy or transport

func NewUtlsHTTPClient

func NewUtlsHTTPClient(ctx context.Context, cfg *config.Config, auth *cliproxyauth.Auth, timeout time.Duration) *http.Client

NewUtlsHTTPClient creates an HTTP client using provider-specific TLS fingerprints for protected hosts. It uses Claude Code's Node/OpenSSL profile for Anthropic and a Chrome profile for ChatGPT, with a standard-transport fallback for other hosts.

func NormalizeOpenAIToolResultsTextOnly added in v7.2.115

func NormalizeOpenAIToolResultsTextOnly(payload []byte) []byte

NormalizeOpenAIToolResultsTextOnly converts tool message content to strings. Text parts are preserved and image parts are replaced with a short marker.

func ObfuscateSensitiveWords

func ObfuscateSensitiveWords(payload []byte, matcher *SensitiveWordMatcher) []byte

ObfuscateSensitiveWords processes the payload and obfuscates sensitive words in system blocks and message content.

func ObfuscateSensitiveWordsInSystemInstruction added in v7.2.118

func ObfuscateSensitiveWordsInSystemInstruction(payload []byte, matcher *SensitiveWordMatcher) []byte

ObfuscateSensitiveWordsInSystemInstruction obfuscates sensitive words in an Antigravity system instruction.

func ObserveChatTokenEvent added in v7.2.146

func ObserveChatTokenEvent(reporter *UsageReporter, payload []byte)

ObserveChatTokenEvent inspects an OpenAI Chat Completions chunk and records TTFT if the frame represents the first meaningful token event. It records first-packet arrival time as fallback and returns immediately with zero allocations once effective token TTFT is set.

func ObserveClaudeTokenEvent added in v7.2.146

func ObserveClaudeTokenEvent(reporter *UsageReporter, payload []byte)

ObserveClaudeTokenEvent inspects an Anthropic Messages SSE chunk and records TTFT if the frame represents the first meaningful token event. It records first-packet arrival time as fallback and returns immediately with zero allocations once effective token TTFT is set.

func ObserveGeminiTokenEvent added in v7.2.146

func ObserveGeminiTokenEvent(reporter *UsageReporter, payload []byte)

ObserveGeminiTokenEvent inspects a Google Gemini / Antigravity streaming chunk and records TTFT if the frame represents the first meaningful token event. It records first-packet arrival time as fallback and returns immediately with zero allocations once effective token TTFT is set.

func ObserveMergedStreamUsage added in v7.2.146

func ObserveMergedStreamUsage(buffer *StreamUsageBuffer, update usage.Detail)

ObserveMergedStreamUsage updates buffer with merged usage details.

func ObservePluginExecutorStreamTTFT added in v7.2.146

func ObservePluginExecutorStreamTTFT(protocol string, reporter *UsageReporter, payload []byte)

ObservePluginExecutorStreamTTFT inspects a streaming payload and records TTFT on the reporter.

func ObservePluginExecutorStreamUsage added in v7.2.146

func ObservePluginExecutorStreamUsage(protocol string, payload []byte, buffer *StreamUsageBuffer)

ObservePluginExecutorStreamUsage parses streaming chunks and updates a stream usage buffer.

func ObserveResponsesTokenEvent added in v7.2.146

func ObserveResponsesTokenEvent(reporter *UsageReporter, payload []byte)

ObserveResponsesTokenEvent inspects a Responses API frame payload and records TTFT if the frame represents the first meaningful token event. It records the first packet arrival time as a fallback and exits immediately with zero allocations once effective token TTFT is set.

func OptimizeCodexMultiAgentV2Request added in v7.2.98

func OptimizeCodexMultiAgentV2Request(ctx context.Context, headers http.Header, payload []byte, cfg *config.Config) ([]byte, bool)

OptimizeCodexMultiAgentV2Request rewrites an eligible spawn_agent request and reports whether the collaboration namespace was renamed for upstream use.

func OptimizeCodexMultiAgentV2RequestForAuth added in v7.2.121

func OptimizeCodexMultiAgentV2RequestForAuth(ctx context.Context, headers http.Header, payload []byte, cfg *config.Config, auth *cliproxyauth.Auth, model string) ([]byte, bool)

OptimizeCodexMultiAgentV2RequestForAuth applies the standard Codex MultiAgentV2 request optimization and, when the selected codex-api-key model has is-compat enabled, also converts agent_message items into portable message/user input.

func ParseAntigravityStreamUsage

func ParseAntigravityStreamUsage(line []byte) (usage.Detail, bool)

func ParseAntigravityUsage

func ParseAntigravityUsage(data []byte) usage.Detail

func ParseClaudeRateLimitReset added in v7.2.133

func ParseClaudeRateLimitReset(headers http.Header, now time.Time) *time.Duration

ParseClaudeRateLimitReset inspects Anthropic response headers for shared and Fable-specific unified rate-limit and standard Retry-After reset information, returning the conservative cooldown duration including a bounded non-negative random grace period. If no valid future reset information is present, it returns nil.

func ParseClaudeStreamUsage

func ParseClaudeStreamUsage(line []byte) (usage.Detail, bool)

func ParseClaudeUsage

func ParseClaudeUsage(data []byte) usage.Detail

func ParseCodexImageToolUsage

func ParseCodexImageToolUsage(data []byte) (usage.Detail, bool)

func ParseCodexQuotaEventHeaders added in v7.2.142

func ParseCodexQuotaEventHeaders(payload []byte) http.Header

ParseCodexQuotaEventHeaders converts one Codex websocket quota event into the same bounded header representation used by HTTP usage observations. Codex sends additional_rate_limits as an object on the websocket path, while the /wham/usage probe exposes the equivalent data as an array; both forms are normalized into namespaced X-Codex headers here.

The websocket payload identifies each additional limit only by limit name ("GPT-5.3-Codex-Spark"), while HTTP responses namespace the same limit by a short name (x-codex-bengalfox-*). The two forms therefore cannot produce identical header names; the X-Codex-Additional- prefix marks the websocket origin, and the snapshot-replacement semantics in QuotaState keep the two spellings from accumulating side by side.

func ParseCodexUsage

func ParseCodexUsage(data []byte) (usage.Detail, bool)

func ParseGeminiStreamUsage

func ParseGeminiStreamUsage(line []byte) (usage.Detail, bool)

func ParseGeminiUsage

func ParseGeminiUsage(data []byte) usage.Detail

func ParseInteractionsStreamUsage added in v7.2.51

func ParseInteractionsStreamUsage(line []byte) (usage.Detail, bool)

func ParseInteractionsUsage added in v7.2.51

func ParseInteractionsUsage(data []byte) usage.Detail

func ParseOpenAIStreamUsage

func ParseOpenAIStreamUsage(line []byte) (usage.Detail, bool)

func ParseOpenAIUsage

func ParseOpenAIUsage(data []byte) usage.Detail

func ParsePluginExecutorResponseUsage added in v7.2.146

func ParsePluginExecutorResponseUsage(protocol string, payload []byte) usage.Detail

ParsePluginExecutorResponseUsage extracts token usage from a non-streaming plugin executor response.

func ParseRetryDelay added in v7.2.20

func ParseRetryDelay(errorBody []byte) (*time.Duration, error)

ParseRetryDelay extracts the retry delay from a Google API 429 error response.

func PayloadRequestPath

func PayloadRequestPath(opts cliproxyexecutor.Options) string

func PayloadRequestedModel

func PayloadRequestedModel(opts cliproxyexecutor.Options, fallback string) string

func PrepareClaudeCLIFingerprintAuth added in v7.2.136

func PrepareClaudeCLIFingerprintAuth(auth *cliproxyauth.Auth, seed string, synthesizeMissing bool) (*cliproxyauth.Auth, error)

PrepareClaudeCLIFingerprintAuth returns the auth object that should receive ApplyClaudeCredentialMetadata. Synthesized API-key / delegated-provider identity is written to a clone so the shared credential metadata map is not mutated on the request path.

func ProviderSessionUUID added in v7.2.101

func ProviderSessionUUID(provider string, metadataSets ...map[string]any) string

ProviderSessionUUID prefers a long-lived execution session and falls back to the derived identity.

func RecordAPIRequest

func RecordAPIRequest(ctx context.Context, cfg *config.Config, info UpstreamRequestLog)

RecordAPIRequest stores the upstream request metadata in Gin context for request logging.

func RecordAPIResponseError

func RecordAPIResponseError(ctx context.Context, cfg *config.Config, err error)

RecordAPIResponseError adds an error entry for the latest attempt when no HTTP response is available.

func RecordAPIResponseMetadata

func RecordAPIResponseMetadata(ctx context.Context, cfg *config.Config, status int, headers http.Header)

RecordAPIResponseMetadata captures upstream response status/header information for the latest attempt.

func RecordAPIWebsocketError

func RecordAPIWebsocketError(ctx context.Context, cfg *config.Config, stage string, err error)

RecordAPIWebsocketError stores an upstream websocket error event in Gin context.

func RecordAPIWebsocketHandshake

func RecordAPIWebsocketHandshake(ctx context.Context, cfg *config.Config, status int, headers http.Header)

RecordAPIWebsocketHandshake stores the upstream websocket handshake response metadata.

func RecordAPIWebsocketRequest

func RecordAPIWebsocketRequest(ctx context.Context, cfg *config.Config, info UpstreamRequestLog)

RecordAPIWebsocketRequest stores an upstream websocket request event in Gin context.

func RecordAPIWebsocketUpgradeRejection

func RecordAPIWebsocketUpgradeRejection(ctx context.Context, cfg *config.Config, info UpstreamRequestLog, status int, headers http.Header, body []byte)

RecordAPIWebsocketUpgradeRejection stores a rejected websocket upgrade as an HTTP attempt.

func RefreshAuthViaHome

func RefreshAuthViaHome(ctx context.Context, cfg *config.Config, auth *cliproxyauth.Auth) (*cliproxyauth.Auth, bool, error)

RefreshAuthViaHome replaces local refresh logic when home control plane integration is enabled. It returns (updatedAuth, true, nil) when home refresh succeeds; (nil, true, err) when home is enabled but refresh fails; and (nil, false, nil) when home is disabled.

func ResetClaudeDeviceProfileCache

func ResetClaudeDeviceProfileCache()

func ResolveAntigravityGroundingURLs added in v7.1.74

func ResolveAntigravityGroundingURLs(ctx context.Context, cfg *config.Config, auth *cliproxyauth.Auth, payload []byte) []byte

ResolveAntigravityGroundingURLs replaces Vertex Search redirect URLs in grounding chunks with their target URLs.

func RestoreCodexMultiAgentV2Response added in v7.2.98

func RestoreCodexMultiAgentV2Response(payload []byte, optimized bool) []byte

RestoreCodexMultiAgentV2Response restores optimized collaboration namespace values before an upstream response is translated and returned to the client.

func RewriteCodexMultiAgentV2Input added in v7.2.98

func RewriteCodexMultiAgentV2Input(ctx context.Context, headers http.Header, payload []byte, cfg *config.Config) []byte

RewriteCodexMultiAgentV2Input converts official Codex multi-agent input into standard Responses API messages when multi-agent v2 optimization is enabled.

func RewriteCodexSpawnAgentDescription added in v7.2.98

func RewriteCodexSpawnAgentDescription(ctx context.Context, headers http.Header, payload []byte, cfg *config.Config) []byte

RewriteCodexSpawnAgentDescription optimizes spawn_agent definitions for official Codex clients when multi-agent v2 optimization is enabled.

func SanitizeCodexInputItemIDs added in v7.2.84

func SanitizeCodexInputItemIDs(body []byte) []byte

SanitizeCodexInputItemIDs normalizes supported input item IDs for Codex, removes encrypted reasoning items whose IDs exceed the Codex limit, and deterministically shortens other overlong input item IDs.

func SetBoolIfDifferent added in v7.2.92

func SetBoolIfDifferent(payload []byte, path string, value bool) []byte

SetBoolIfDifferent updates path only when its value is not already the canonical JSON boolean. Values with another JSON type are still normalized.

func SetCodexCache

func SetCodexCache(key string, cache CodexCache)

SetCodexCache stores a cache entry.

func SetCodexCacheBestEffort added in v7.2.0

func SetCodexCacheBestEffort(ctx context.Context, key string, cache CodexCache) bool

SetCodexCacheBestEffort stores a cache entry without failing completed responses.

func SetCodexCacheRequired added in v7.2.0

func SetCodexCacheRequired(ctx context.Context, key string, cache CodexCache) error

SetCodexCacheRequired stores a cache entry for request-time paths.

func SetRawIfDifferent added in v7.2.92

func SetRawIfDifferent(payload []byte, path string, value []byte) []byte

SetRawIfDifferent updates path only when the existing raw JSON is identical.

func SetStringIfDifferent added in v7.2.92

func SetStringIfDifferent(payload []byte, path, value string) []byte

SetStringIfDifferent updates path only when its value is not already the canonical JSON string. Values with another JSON type are still normalized.

func ShouldNormalizeOpenAIToolResultsForModel added in v7.2.115

func ShouldNormalizeOpenAIToolResultsForModel(compat *config.OpenAICompatibility, upstreamModel, requestedModel string) bool

ShouldNormalizeOpenAIToolResultsForModel reports whether the selected model explicitly excludes image input through its input-modalities configuration.

func StableClaudeCLIAccountUUID added in v7.2.137

func StableClaudeCLIAccountUUID(seed string) string

StableClaudeCLIAccountUUID returns a deterministic UUIDv5 account ID derived from a seed.

func StableClaudeCLIDeviceID added in v7.2.137

func StableClaudeCLIDeviceID(seed string) string

StableClaudeCLIDeviceID returns a deterministic device ID derived from a seed.

func StripUsageMetadataFromJSON

func StripUsageMetadataFromJSON(rawJSON []byte) ([]byte, bool)

StripUsageMetadataFromJSON drops usageMetadata unless finishReason is present (terminal). It handles both formats: - Aistudio: candidates.0.finishReason - Antigravity: response.candidates.0.finishReason

func StripVertexOpenAIResponsesToolCallIDs

func StripVertexOpenAIResponsesToolCallIDs(payload []byte, sourceFormat string) []byte

StripVertexOpenAIResponsesToolCallIDs removes OpenAI Responses call IDs that Vertex rejects in Gemini functionCall/functionResponse payloads.

func SummarizeErrorBody

func SummarizeErrorBody(contentType string, body []byte) string

func TokenizerForModel

func TokenizerForModel(model string) (tokenizer.Codec, error)

TokenizerForModel returns a tokenizer codec suitable for an OpenAI-style model id.

func TranslateRequestPairWithCodexMultiAgentV2 added in v7.2.129

func TranslateRequestPairWithCodexMultiAgentV2(ctx context.Context, headers http.Header, cfg *config.Config, from, to sdktranslator.Format, model string, originalPayload, requestPayload []byte, stream bool) (original, working []byte)

TranslateRequestPairWithCodexMultiAgentV2 translates the untouched baseline payload and the working payload that later stages mutate in place. Executors normally assign the original payload to the request before translating, so both translations would rescan the same bytes and produce the same result. Built-in request translation is deterministic, so that case is translated once and duplicated when no plugin hooks are installed. Hooks retain two invocations because they may have request-scoped output or side effects. This removes a full extra pass over payloads that can reach tens of megabytes.

func TranslateRequestWithAPIKeyModelCompatibility added in v7.2.121

func TranslateRequestWithAPIKeyModelCompatibility(ctx context.Context, headers http.Header, cfg *config.Config, from, to sdktranslator.Format, model string, payload []byte, stream, isCompat bool) []byte

TranslateRequestWithAPIKeyModelCompatibility applies compatibility-aware request translators when a configured API-key model enables compatibility mode.

func TranslateRequestWithCodexMultiAgentV2 added in v7.2.98

func TranslateRequestWithCodexMultiAgentV2(ctx context.Context, headers http.Header, cfg *config.Config, from, to sdktranslator.Format, model string, payload []byte, stream bool) []byte

TranslateRequestWithCodexMultiAgentV2 normalizes official Codex multi-agent input before translating it to a non-Codex target protocol.

func TranslateStreamWithClaudeInputTokens added in v7.2.95

func TranslateStreamWithClaudeInputTokens(
	ctx context.Context,
	upstreamFormat, responseFormat sdktranslator.Format,
	model string,
	originalRequestRawJSON, requestRawJSON, rawJSON []byte,
	param *any,
	state *ClaudeInputTokenState,
) [][]byte

TranslateStreamWithClaudeInputTokens translates a stream chunk and estimates Claude message_start input usage once.

func WebsocketUpgradeRequestURL

func WebsocketUpgradeRequestURL(rawURL string) string

WebsocketUpgradeRequestURL converts a websocket URL back to its HTTP handshake URL for logging.

Types

type ClaudeCodeRequestDetection added in v7.2.116

type ClaudeCodeRequestDetection struct {
	Confirmed       bool
	StrongSignals   bool
	NativeClient    bool
	XAppCLI         bool
	UserAgent       bool
	BetasPresent    bool
	MetadataUserID  bool
	HelperProfile   bool
	Entrypoint      string
	Subclient       string
	AgentSDKVersion string
}

ClaudeCodeRequestDetection records the strong signals and first-party subclient identity used to distinguish an official Claude Code request from a client that only copied its User-Agent.

func DetectClaudeCodeRequest added in v7.2.116

func DetectClaudeCodeRequest(headers http.Header, payload []byte, countTokens bool, configs ...*config.Config) ClaudeCodeRequestDetection

DetectClaudeCodeRequest first mirrors CCH's strong-signal contract, then applies CPA's native-client policy. Standard Messages requests require all four strong signals; count_tokens omits metadata.user_id. A separate narrow profile recognizes measured native Haiku helper requests that intentionally omit claude-code-20250219. Generic sdk-ts/sdk-py Agent SDK entrypoints remain unconfirmed and receive CLI cloaking.

type ClaudeDeviceProfile

type ClaudeDeviceProfile struct {
	UserAgent      string
	PackageVersion string
	RuntimeVersion string
	OS             string
	Arch           string
	// contains filtered or unexported fields
}

func ResolveClaudeDeviceProfile

func ResolveClaudeDeviceProfile(auth *cliproxyauth.Auth, apiKey string, headers http.Header, cfg *config.Config) ClaudeDeviceProfile

func ResolveClaudeDeviceProfileRequired added in v7.2.0

func ResolveClaudeDeviceProfileRequired(ctx context.Context, auth *cliproxyauth.Auth, apiKey string, headers http.Header, cfg *config.Config) (ClaudeDeviceProfile, error)

ResolveClaudeDeviceProfileRequired resolves a stable Claude Code device profile for request-time paths.

type ClaudeInputTokenState added in v7.2.95

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

ClaudeInputTokenState tracks the one-time input token update for a translated Claude stream.

func NewClaudeInputTokenState added in v7.2.95

func NewClaudeInputTokenState(sourceFormat, upstreamFormat, responseFormat sdktranslator.Format, originalRequest []byte) *ClaudeInputTokenState

NewClaudeInputTokenState creates request-scoped state for translated Claude input token usage.

type CodexCache

type CodexCache struct {
	ID     string
	Expire time.Time
}

func ClaudeCodePromptCache added in v7.2.30

func ClaudeCodePromptCache(ctx context.Context, modelName string, payload []byte, headers http.Header) (CodexCache, bool, error)

ClaudeCodePromptCache derives a deterministic upstream prompt_cache_key for one Claude Code agent.

func GetCodexCache

func GetCodexCache(key string) (CodexCache, bool)

GetCodexCache retrieves a cached entry, returning ok=false if not found or expired.

func GetCodexCacheRequired added in v7.2.0

func GetCodexCacheRequired(ctx context.Context, key string) (CodexCache, bool, error)

GetCodexCacheRequired retrieves a cached entry for request-time paths.

type SensitiveWordMatcher

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

SensitiveWordMatcher holds the compiled regex for matching sensitive words.

func BuildSensitiveWordMatcher

func BuildSensitiveWordMatcher(words []string) *SensitiveWordMatcher

BuildSensitiveWordMatcher compiles a regex from the word list. Words are sorted by length (longest first) for proper matching.

type StreamUsageBuffer added in v7.2.52

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

StreamUsageBuffer keeps the latest usage detail observed in a stream.

func (*StreamUsageBuffer) Detail added in v7.2.52

func (b *StreamUsageBuffer) Detail() (usage.Detail, bool)

Detail returns the latest observed usage detail.

func (*StreamUsageBuffer) Observe added in v7.2.52

func (b *StreamUsageBuffer) Observe(detail usage.Detail, ok bool)

Observe records detail when ok is true, allowing the final stream usage to win.

func (*StreamUsageBuffer) ObserveOpenAIStream added in v7.2.65

func (b *StreamUsageBuffer) ObserveOpenAIStream(line []byte)

ObserveOpenAIStream records response-tier state and the latest usage from an OpenAI-style stream while avoiding JSON parsing for irrelevant chunks.

func (*StreamUsageBuffer) Publish added in v7.2.52

func (b *StreamUsageBuffer) Publish(ctx context.Context, reporter *UsageReporter) bool

Publish emits the latest observed usage detail, if any.

func (*StreamUsageBuffer) PublishFailure added in v7.2.137

func (b *StreamUsageBuffer) PublishFailure(ctx context.Context, reporter *UsageReporter, errs ...error) bool

PublishFailure emits the latest observed usage detail together with failure details.

type TransportCache added in v7.2.129

type TransportCache[K comparable] struct {
	// contains filtered or unexported fields
}

TransportCache memoizes HTTP transports under a comparable key using a bounded LRU. Evicting an entry closes its idle connections so neither the pool nor its background goroutines outlive the cache entry.

The key type is generic so callers can mix value identity (a normalized proxy URL) with pointer identity (a base transport supplied by the caller) without the cache retaining either beyond the LRU window.

func NewTransportCache added in v7.2.129

func NewTransportCache[K comparable](capacity int) *TransportCache[K]

NewTransportCache returns a cache holding at most capacity transports. A non-positive capacity falls back to DefaultTransportCacheCapacity.

func (*TransportCache[K]) Get added in v7.2.129

func (c *TransportCache[K]) Get(key K, build func() (*http.Transport, error)) (*http.Transport, error)

Get returns the transport cached under key, calling build on the first use of that key. Concurrent callers observe the same instance.

A build error is propagated without being cached, so a later call can retry and a failed lookup never occupies a cache slot. build must not call back into the same cache.

func (*TransportCache[K]) Len added in v7.2.129

func (c *TransportCache[K]) Len() int

Len reports how many transports the cache currently holds.

func (*TransportCache[K]) Purge added in v7.2.129

func (c *TransportCache[K]) Purge()

Purge drops every entry and closes the idle connections it was holding.

type UpstreamRequestLog

type UpstreamRequestLog struct {
	URL       string
	Method    string
	Headers   http.Header
	Body      []byte
	Provider  string
	AuthID    string
	AuthLabel string
	AuthType  string
	AuthValue string
}

UpstreamRequestLog captures the outbound upstream request details for logging.

type UsageReporter

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

func NewExecutorUsageReporter added in v7.1.38

func NewExecutorUsageReporter(ctx context.Context, executor usageExecutor, model string, auth *cliproxyauth.Auth) *UsageReporter

func NewUsageReporter

func NewUsageReporter(ctx context.Context, provider, model string, auth *cliproxyauth.Auth) *UsageReporter

func (*UsageReporter) EnsurePublished

func (r *UsageReporter) EnsurePublished(ctx context.Context)

ensurePublished guarantees that a usage record is emitted exactly once. It is safe to call multiple times; only the first call wins due to once.Do. This is used to ensure request counting even when upstream responses do not include any usage fields (tokens), especially for streaming paths.

func (*UsageReporter) IsFirstPacketSet added in v7.2.146

func (r *UsageReporter) IsFirstPacketSet() bool

func (*UsageReporter) IsTTFTSet added in v7.2.146

func (r *UsageReporter) IsTTFTSet() bool

func (*UsageReporter) MarkFirstResponseByte added in v7.1.24

func (r *UsageReporter) MarkFirstResponseByte()

func (*UsageReporter) ObserveResponse added in v7.1.24

func (r *UsageReporter) ObserveResponse(resp *http.Response)

func (*UsageReporter) ObserveResponsePacketOnly added in v7.2.146

func (r *UsageReporter) ObserveResponsePacketOnly(resp *http.Response)

func (*UsageReporter) ObserveTokenEvent added in v7.2.146

func (r *UsageReporter) ObserveTokenEvent(isToken bool)

ObserveTokenEvent records the first packet fallback time on the first frame, and if isToken is true, records the effective TTFT. It uses a fast-path read check to return immediately with zero write lock contention once TTFT is set or when subsequent non-token metadata frames arrive after the first packet.

func (*UsageReporter) Publish

func (r *UsageReporter) Publish(ctx context.Context, detail usage.Detail)

func (*UsageReporter) PublishAdditionalModel

func (r *UsageReporter) PublishAdditionalModel(ctx context.Context, model string, detail usage.Detail)

func (*UsageReporter) PublishFailure

func (r *UsageReporter) PublishFailure(ctx context.Context, errs ...error)

func (*UsageReporter) PublishFailureWithDetail added in v7.2.137

func (r *UsageReporter) PublishFailureWithDetail(ctx context.Context, detail usage.Detail, errs ...error)

func (*UsageReporter) RecordFirstPacket added in v7.2.146

func (r *UsageReporter) RecordFirstPacket()

RecordFirstPacket records the arrival time of the first packet/chunk from upstream as a fallback.

func (*UsageReporter) SetStream added in v7.2.147

func (r *UsageReporter) SetStream(stream bool)

SetStream records whether the request was executed in streaming mode.

func (*UsageReporter) SetTranslatedReasoningEffort added in v7.1.24

func (r *UsageReporter) SetTranslatedReasoningEffort(payload []byte, format string)

func (*UsageReporter) StartResponseTTFT added in v7.1.24

func (r *UsageReporter) StartResponseTTFT()

func (*UsageReporter) TrackFailure

func (r *UsageReporter) TrackFailure(ctx context.Context, errPtr *error)

func (*UsageReporter) TrackHTTPClient added in v7.1.24

func (r *UsageReporter) TrackHTTPClient(client *http.Client) *http.Client

func (*UsageReporter) TrackHTTPClientRoundTripOnly added in v7.2.146

func (r *UsageReporter) TrackHTTPClientRoundTripOnly(client *http.Client) *http.Client

TrackHTTPClientRoundTripOnly records the TTFT start time upon sending the request and captures first-packet arrival fallback on initial body reads, while keeping effective TTFT unset. This allows protocol-aware streaming executors (like Codex SSE) to mark effective TTFT explicitly upon receiving substantive token events, while preserving first-packet fallback metrics for non-2xx error bodies or keepalive streams.

func (*UsageReporter) UpdateAccessTokenFingerprint added in v7.2.116

func (r *UsageReporter) UpdateAccessTokenFingerprint(auth *cliproxyauth.Auth)

UpdateAccessTokenFingerprint records the token version actually used upstream.

Jump to

Keyboard shortcuts

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