userSessionsKey generates a secure Redis key for user's session set using HMAC-SHA256 This prevents user ID enumeration and links session hashes to us

validateContainerPath validates paths for container operations. Ensures paths stay within containerWorkspaceRoot.

===================================================================== HELPER FUNCTIONS ===============================================================

Allocate assigns the next available port

============================================================================= HELPER FUNCTIONS =======================================================

CreateCRMDeal creates a new CRM deal

CreateProject creates a new project.

NOTE: Route registration happens in handlers.go (lines 1360-1367) Routes use /deployment namespace to avoid conflicts with /apps/:id wildcard Deployme

Enqueue adds a suggestion as a pending ImprovementTask and returns the assigned task ID.

Enqueue is the single fire-and-forget entrypoint modules use. Errors are logged but never returned — the calling handler should not fail because the e

GenerateApp triggers application generation in OSA.

Get retrieves a session by ID

GetActionHandler retrieves an action handler by name.

GetMetrics returns a snapshot of worker pool metrics

GetProfile retrieves an application profile

GetSandboxInfo retrieves information about a sandbox.

GetTasksAPI returns a Google Tasks API service for a user.

HasPermission checks if the user has a specific permission on a resource

IsAtLeastLevel checks if user's hierarchy level is at or above the specified level Lower numbers = higher hierarchy (e.g., 1 = owner, 2 = admin, 3 = m

Limit returns the limit value (same as PerPage)

Lookup returns the competence entry for the given agent+genre, or nil if not found. Falls back to "orchestrator" competence if the specific agent has

Match finds the best matching SORX skill for the given user message. Returns nil if no skill meets the confidence threshold.

============================================================================= COMMON ERROR RESPONSES =================================================

NewAlgedonicChannel creates a new AlgedonicChannel with the given handlers.

NewClientAgent creates a new client agent

NewCodeToolRegistry creates a new code tool registry

NewCompetenceRegistry creates a pre-populated CompetenceRegistry with defaults. Since the Orchestrator handles all traffic (self-routing), defaults ar

NewDocumentAgent creates a new document agent

NewHealthHandler constructs a HealthHandler. - pool — pass nil when the database is not yet available (degraded mode). - redis — pass nil when Redis

NewImprovementTaskQueue constructs an ImprovementTaskQueue. engine is used to update Q-values when tasks are applied.

NewOrchestrator creates a new orchestrator agent

NewSanitizedLogger creates a new sanitized logger

NewSyncHandler creates a new SyncHandler.

NewValidationError creates a non-retryable input validation error.

Observe fires the full observation pipeline asynchronously. Zero latency on the hot path — launches a goroutine and returns immediately.

Pool returns the database pool.

RemoveAppContainer removes an app container.

For output style specific instructions

Snapshot returns a point-in-time snapshot of metrics

Subscribe creates a channel for a user. Returns nil if the per-user connection limit has been reached.

SyncTemplates syncs all YAML templates to the database. Strategy: YAML files are the source of truth.

TransformProjectRows transforms ListProjectsRow to a clean JSON response.

ValidateChange checks if a proposed change is allowed by the module's protection rules

ValidateVariables validates that all required variables are present and have correct types

Verify runs all three verification layers against a signal and returns a VerificationResult. The composite score is the weighted sum of layer scores.

* Ask the second brain a question. Curated wiki first, hybrid search second. * Returns an ACL-scoped, audience-shaped, bandwidth-matched envelope w

============================================================================= HELPER FUNCTIONS =======================================================

============================================================================= INTERNAL HELPERS =======================================================

buildPrompt constructs the generation prompt from template or config. Priority order for the base prompt: 1. Template generation_prompt (when template

createAgentAction creates an action handler for a specific agent type.

createProgressEvent serialises a ProgressEvent. If JSON marshalling fails the function returns a safe minimal fallback string rather than an error, be

defaultRewardWeights returns conservative defaults. All types are 1.0 except LatencyOptimization which is 0.8 (deprioritised vs correctness).

* Add an operation to the sync queue

============================================================================ GraphQL Methods =========================================================

formatEngineResponse extracts the human-readable text from an engine response map. Falls through several common shapes — answer, body, summary, conten

* Get a single record by ID

getString safely extracts a string value from a map

getStringSlice safely extracts a string slice from a map

getTableNames returns all table names in the current database

* Helper to handle API responses

Helper function to check if error wraps a specific quota error

isSecureCookie determines if cookies should use the Secure flag. Returns true in production or when the request is already over HTTPS.

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

mustParseTime is a small test helper that panics rather than returning an error so table-driven tests stay compact.

newTestProtectionService creates a ModuleProtectionService with a nil pool suitable for calling check* methods that do not hit the database.

Helper function to convert empty string to nil pointer

pgTypeUUID converts uuid.UUID to pgtype.UUID

remoteGet does an authenticated GET against the configured base URL and JSON-decodes the response into out.

requireUserID ensures the user is authenticated. Returns the userID if authenticated, or sends an error response and returns empty string.

======================================== HELPER FUNCTIONS ========================================

rollback restores a Sprite from a checkpoint tag after a failed upgrade step. It logs the restoration attempt and wraps both the original error and an

sanitizeContainerPath validates and sanitizes a container path CRITICAL SECURITY FUNCTION - prevents path traversal attacks

* Hybrid semantic + keyword search across memory.

Send a user message to the running agent's stdin

setupOSATemplateTestRouter creates a test router with auth middleware for OSA templates

Map an HTTP status code to the appropriate exception class.

Helper function to convert pgtype.UUID to string