newTestModeTransitionService builds a ModeTransitionService without a DB pool. All tests that exercise in-memory logic can safely use nil as the pool;

newTestRegistry creates a Registry backed by a no-op slog logger.

retryWithBackoff executes a function with exponential backoff retry logic.

setupTestContext creates a Gin test context for middleware testing

setupTestHandlers creates a test AppHandler instance with database

setupTestRouter creates a Gin router with test routes

sleepContext blocks for d or until ctx is cancelled, whichever comes first.

testOSAConfig creates an OSA config suitable for unit tests (with mock server)

Helper functions (package-level, shared within handlers package)

updateAppStatus updates the app status in the database.

verifySignature verifies the HMAC signature of the webhook. Production (isProduction == true): a missing or invalid signature ALWAYS results in rejec

Check performs a health check with caching

CheckQuota validates if a user can allocate the requested resources. Returns nil if quota allows the request, otherwise returns a quota error.

ChunkPlainText chunks plain text respecting natural boundaries

CreateNode creates a new node

CreateSnapshot captures the current workspace state as a new version

DefaultLogConfig returns production-safe defaults

DefaultSanitizerConfig returns production-safe defaults

DeleteByPattern removes all cache entries matching a pattern

EstimateTokens estimates the token count for a string (approximation)

Get retrieves a provider by name. Returns the provider and true if found, nil and false otherwise.

GetSetpoint returns the setpoint for the named metric.

GetTemplatesDirectory returns the absolute path to the OSA templates directory

GetToken retrieves OAuth tokens for a user.

IncrementErrors increments the total errors counter

IncrementStopped increments the total stopped counter

IsConnected reports whether the underlying AMQP channel is ready for use.

IsEnabled returns whether the email service is configured and enabled

NewAnalystAgent creates a new analyst agent

NewAppGenerationOrchestrator creates a production-ready orchestrator

NewDoubleLoopController creates a new DoubleLoopController.

NewFocusService creates a new focus service

NewInMemorySetpointStore creates a store pre-loaded with default setpoints. Default thresholds: action_completion_rate: 80% ± 10% (Shannon channel

NewInputSanitizer creates a new sanitizer with compiled patterns

NewSandboxDeploymentService creates a new sandbox deployment service.

NewSessionCache creates a new Redis-backed session cache If cfg.HMACSecret is empty, generates a random secret (development mode only) CRITICAL: In pr

NewSubconsciousHintProvider creates a new provider that composes PromptActuator hints with subconscious memory blocks.

NewTemplateSyncService creates a new template sync service.

NewVerifier constructs a Verifier with all three validation layers. All validators are required. Uses DefaultVerificationThreshold if threshold is 0.

ProcessChunk processes a chunk from the LLM and writes events

Publish sends a message to a channel

SetEngineSync wires the shared service. Called once from route registration right after the handler is constructed.

Options

ValidateVariableType checks if a variable value matches the expected type

Connect and launch the agent

copyMetadata creates a copy of metadata map

crmJSONBytes converts an arbitrary value to JSON bytes for a JSONB column. Returns nil (SQL NULL) for empty/nil inputs so pgx doesn't send the bytes t

============================================================================ HELPER FUNCTIONS (CRM-specific to avoid redeclaration) ==================

deduplicateMemories removes duplicate memories

---- internal HTTP helper ---------------------------------------------------- do is the single choke-point for all HTTP calls. It serialises the requ

emit is the internal helper that guards against nil broadcasters and empty workflow IDs before invoking the broadcaster.

evictBlocks removes lowest priority blocks until tokensNeeded are freed

extractDomain extracts the domain from a URL

extractTags extracts relevant tags from text

generateFileID creates a stable, unique ID for a file path.

generateHint produces a behavioral hint string for agents based on health signals.

generateUnifiedDiff creates a unified diff by delegating to the shared computeUnifiedDiff (workspace_version_service.go) and adding truncation support

Fetch one memory by id.

These tests require OSA to be running on localhost:8089 Run with: go test -tags=integration ./internal/integrations/osa/...

============================================================================ Helpers =================================================================

Shared test helper functions limitString truncates a string to a maximum length

nullableString converts an empty string to nil so Postgres gets a proper NULL.

resolveWorkflowSearch returns the search arguments for queries that accept either a UUID or a workflow ID prefix.

sanitizeContent replaces problematic Unicode characters with ASCII equivalents

sessionKey generates a secure Redis key for a session using HMAC-SHA256 This prevents enumeration attacks by hashing the session ID before using it as

setupTestDB creates a test database connection Uses testcontainers pattern from existing tests

setupTestTempWorkspace creates a temporary workspace directory for file operations

teamWorkspace returns the workspace id that owns a team.

testSandboxConfig creates a config for tests

testSandboxLogger creates a logger for tests

truncateString returns s truncated to maxLen characters, appending "..." when truncation occurs.

updateSandboxStatus updates the sandbox status in the database.