diff --git a/packages/app/server/AGENTS.md b/packages/app/server/AGENTS.md new file mode 100644 index 000000000..dc6401513 --- /dev/null +++ b/packages/app/server/AGENTS.md @@ -0,0 +1,41 @@ +# Server Configuration Modules (packages/app/server) + +## Purpose +This cluster manages configuration files for the server environment, including testing, build, and linting setups. It ensures consistent tooling behavior across development and CI environments. + +## Boundaries +- **Belongs here:** `vitest.config.ts`, `tsup.config.ts`, `eslint.config.mjs`—all define environment-specific tooling configurations. +- **Does NOT belong here:** Application business logic, runtime server code, or deployment scripts. These configs are static and do not influence runtime behavior directly. + +## Invariants +- All configuration files must export a default configuration object via `defineConfig`. +- Config files should avoid side effects; they are purely declarative. +- The `vitest.config.ts` and `tsup.config.ts` are frequently updated, so agents must handle potential breaking changes or schema updates. +- ESLint config (`eslint.config.mjs`) must adhere to ECMAScript Module syntax and be compatible with the project's linting standards. +- No circular dependencies should exist between configs; each should be self-contained. + +## Patterns +- Use `defineConfig` to wrap configuration objects for type safety and consistency. +- Maintain naming conventions: `vitest.config.ts`, `tsup.config.ts`, `eslint.config.mjs`. +- For TypeScript configs, prefer explicit types where possible. +- Handle errors gracefully; configs should fail to load if invalid, but avoid silent failures. +- Keep configurations minimal; extend base configs only when necessary. +- Frequently modified files (5 versions each) suggest the need for careful review when editing to prevent breaking changes. + +## Pitfalls +- Modifying `vitest.config.ts` or `tsup.config.ts` without updating related build/test scripts can cause environment failures. +- Changing ESLint config syntax or rules may silently break linting if not validated. +- Overriding default behaviors in configs may lead to inconsistent tooling behavior. +- Frequent churn indicates these configs are sensitive; avoid unnecessary modifications. +- Be cautious with dependencies imported into configs; ensure they are compatible and correctly versioned. + +## Dependencies +- `defineConfig` from the relevant configuration libraries (e.g., Vite, Tsup, ESLint). Use it to ensure proper typing and structure. +- External plugins or presets used within configs must be compatible with the current versions. +- Do not introduce runtime dependencies into static configs unless explicitly supported; configs should be self-contained. +- When extending configs, verify that dependencies are correctly installed and compatible with the existing setup. + +--- + +**Summary:** +This cluster encapsulates static tooling configurations critical for development consistency. Agents must handle frequent updates, avoid breaking invariants, and respect the separation from runtime code. Proper use of `defineConfig` and adherence to naming, syntax, and dependency standards are essential for stability. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_defines_provider_typ_5e8780f9.md b/packages/app/server/src/AGENTS_defines_provider_typ_5e8780f9.md new file mode 100644 index 000000000..ddfec59e0 --- /dev/null +++ b/packages/app/server/src/AGENTS_defines_provider_typ_5e8780f9.md @@ -0,0 +1,47 @@ +# ProviderType Module & createX402Transaction Method + +## Purpose +Defines provider types used for transaction processing and implements `createX402Transaction`, an async method that generates a `TransactionCosts` object based on a given `Transaction`. This facilitates dynamic transaction cost calculation within the provider ecosystem. + +## Boundaries +- **Belongs here:** + - Provider type definitions (`ProviderType.ts`) that categorize or configure different transaction providers. + - Implementation of `createX402Transaction`, which encapsulates logic for creating a specific transaction cost report. +- **Does NOT belong here:** + - Core transaction processing logic unrelated to provider types. + - External API integrations or database access—these should be abstracted or delegated elsewhere. + - Utility functions or shared helpers unrelated to provider type definitions or transaction cost creation. + +## Invariants +- `createX402Transaction` must always return a `TransactionCosts` object, never null or undefined. +- The method should handle all `Transaction` inputs gracefully, including invalid or incomplete data, by throwing or returning error states as per the application's error handling pattern. +- The `Transaction` parameter must be validated before processing; invalid transactions should not produce a `TransactionCosts` object. +- The function must preserve data integrity: no mutation of input `Transaction`, and all outputs must accurately reflect the input's details plus calculated costs. +- The method must respect the contract that it is asynchronous; any synchronous operations should be wrapped or awaited appropriately. +- Provider types in `ProviderType.ts` should be immutable or controlled; avoid runtime modifications that could break type assumptions. + +## Patterns +- Use explicit, descriptive naming for variables and functions; e.g., `createX402Transaction`. +- Implement comprehensive error handling: catch exceptions, validate inputs, and propagate errors in a consistent manner. +- Follow the project's coding style for async functions, including proper use of `await`. +- When modifying, ensure that any new provider types or transaction cost calculations adhere to existing data schemas and validation rules. +- Maintain separation of concerns: `ProviderType.ts` should only define types/constants; `createX402Transaction` should focus solely on transaction cost creation logic. + +## Pitfalls +- **Churn risk:** Both the module and method are frequently modified; introducing incompatible changes can break assumptions. +- **Coupling:** Since the method depends on `Transaction` and returns `TransactionCosts`, ensure these types are stable; avoid tight coupling to external modules that may change. +- **Null safety:** Failing to validate `Transaction` inputs could lead to runtime errors or inconsistent `TransactionCosts`. +- **Type assumptions:** Misalignment between `Transaction` and `TransactionCosts` schemas can cause subtle bugs; enforce strict validation. +- **Asynchronous handling:** Forgetting to `await` the async method can cause unpredictable behavior downstream. +- **Provider type modifications:** Changes in `ProviderType.ts` should be reflected in all dependent logic to prevent mismatches. + +## Dependencies +- **Transaction:** Must be validated and processed according to its schema; ensure any updates to `Transaction` are reflected here. +- **TransactionCosts:** The output schema; understand its fields and constraints to produce valid results. +- **TypeScript types:** Use the types from `ProviderType.ts` to enforce correct provider categorization. +- **Error handling conventions:** Follow existing patterns for propagating errors from `createX402Transaction`. +- **External configs or constants:** If any provider-specific parameters are used, ensure they are correctly imported and used consistently. + +--- + +**Note:** Be vigilant about frequent modifications in both the module and method—test thoroughly after changes to prevent regressions. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_encapsulates_logic_5da8044e.md b/packages/app/server/src/AGENTS_encapsulates_logic_5da8044e.md new file mode 100644 index 000000000..c68304cfc --- /dev/null +++ b/packages/app/server/src/AGENTS_encapsulates_logic_5da8044e.md @@ -0,0 +1,70 @@ +# Package: packages/app/server/src + +## Purpose +Encapsulates server-side logic for user spend management and error handling, focusing on retrieving balances, updating user spend pools, and managing upstream response errors. It provides core transactional and error-resilient operations critical to financial workflows. + +## Boundaries +- **Includes:** + - `getBalance()`: Fetches total user balance, likely from a database or cache. + - `upsertUserSpendPoolUsage()`: Atomically updates or inserts user spend pool records within a Prisma transaction, ensuring data consistency during concurrent operations. + - `handleUpstreamError()`: Processes upstream HTTP responses, throwing or handling errors based on response status or content. + +- **Excludes:** + - User authentication/authorization logic (should be handled upstream). + - External payment gateways or external API integrations beyond response error handling. + - Business logic for spend pool creation, deletion, or complex validation (beyond basic upsert). + - UI rendering or client-side code. + - Non-transactional data retrieval or background jobs. + +## Invariants +- `upsertUserSpendPoolUsage()` must be invoked within an active Prisma transaction (`tx`) to ensure atomicity. +- `getBalance()` must return a non-negative number; if negative, it indicates a data inconsistency. +- `handleUpstreamError()` must never swallow errors silently; it should throw or escalate after processing. +- All methods assume proper dependency injection; no internal state is maintained. +- Null or undefined `userId`, `spendPoolId`, or `amount` parameters are invalid; validation should be enforced externally or at call sites. +- `amount` must be a `Decimal` object, not a primitive number, to avoid precision errors. +- Response handling in `handleUpstreamError()` should consider HTTP status codes and response body content to determine error severity. + +## Patterns +- Use explicit async/await syntax for all I/O operations. +- Consistent error handling: `handleUpstreamError()` processes `Response` objects, throwing on error status. +- Transactional integrity: `upsertUserSpendPoolUsage()` requires a Prisma `TransactionClient` passed explicitly, emphasizing explicit transaction boundaries. +- Naming conventions: + - Methods prefixed with `get` or `fetch` for retrieval. + - Methods prefixed with `upsert` for create/update logic. + - Error handling methods prefixed with `handle`. +- Decimal usage for monetary amounts to prevent floating-point inaccuracies. +- Frequent modifications suggest these methods are core to spend and balance logic, requiring careful change management. + +## Pitfalls +- **Churn Hotspots:** + - `getBalance()`, `upsertUserSpendPoolUsage()`, `handleUpstreamError()` have high churn; modifications risk introducing regressions or inconsistencies. + - Changes to `getBalance()` must consider caching or external data sources; frequent updates may affect performance or correctness. + - `upsertUserSpendPoolUsage()` must handle concurrent updates; improper transaction handling can cause race conditions or data corruption. + - `handleUpstreamError()` must correctly interpret varied response formats; misinterpretation can lead to unhandled errors or silent failures. + +- **Common mistakes:** + - Omitting transaction context in `upsertUserSpendPoolUsage()`. + - Not validating input parameters before calling these methods. + - Ignoring the need for consistent error propagation in `handleUpstreamError()`. + - Assuming `getBalance()` is always accurate without considering cache invalidation or external data refresh. + +## Dependencies +- **Prisma.TransactionClient:** + - Must be a valid Prisma transaction context; ensure caller manages transaction lifecycle. + - Do not reuse transaction clients outside their scope. + +- **Decimal:** + - Use the `Decimal` class for `amount` to maintain precision; avoid primitive number types. + +- **Response (globalThis.Response):** + - Handle HTTP status codes (e.g., 4xx, 5xx) explicitly; consider response body content for detailed error info. + - Do not assume all responses are successful; always check status before processing. + +- **External APIs:** + - No external dependencies are directly imported; assume all external interactions are via `Response` objects passed to `handleUpstreamError()`. + +--- + +**Note:** +Agents modifying this code should prioritize maintaining transactional integrity, input validation, and error handling consistency. Frequent churn areas require thorough testing to prevent regressions. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_implements_an_expres_f061fb01.md b/packages/app/server/src/AGENTS_implements_an_expres_f061fb01.md new file mode 100644 index 000000000..5d21f2598 --- /dev/null +++ b/packages/app/server/src/AGENTS_implements_an_expres_f061fb01.md @@ -0,0 +1,47 @@ +# Trace Logging Middleware (packages/app/server/src) + +## Purpose +Implements an Express middleware function `traceLoggingMiddleware` that logs request details for tracing and debugging purposes. It ensures consistent logging for incoming requests and their lifecycle within the server. + +## Boundaries +- **Belongs here:** Request lifecycle logging, middleware setup, request context enrichment. +- **Does NOT belong here:** Business logic, route handling, response formatting, error handling beyond logging, schema definitions (handled in `descriptionForRoute.ts`), or external request processing. + +## Invariants +- `traceLoggingMiddleware` must always call `next()` exactly once, regardless of errors. +- It must log at the start of request processing and after response is sent, capturing request method, URL, headers, and response status. +- Null-safety: `req`, `res`, and `next` are guaranteed to be non-null; no null checks needed. +- Response status should be captured after response finishes, not before. +- Logging should not block or delay response; perform asynchronously if needed. +- Middleware must not modify `req` or `res` objects unless explicitly intended for tracing. +- Churn: Frequently modified (5 versions); ensure backward compatibility with previous logging formats. + +## Patterns +- Use consistent naming: `traceLoggingMiddleware`. +- Log request details at the start (`req.method`, `req.url`, headers) and after response (`res.statusCode`). +- Attach event listeners to `res` (`finish` event) for capturing response completion. +- Handle errors gracefully; ensure `next()` is called even if logging fails. +- Use external dependencies (`bodies`, `response`, `status`) for structured logging and response handling. +- Maintain idempotency: middleware should be safe to call multiple times without side effects. +- Follow existing code style: arrow functions, explicit types, minimal side effects. + +## Pitfalls +- Forgetting to call `next()`, causing request hang or deadlock. +- Logging after response has already been sent, missing status code. +- Not handling errors in logging, leading to unhandled exceptions. +- Modifying request or response objects unintentionally. +- Churn: frequent modifications increase risk of breaking invariants; test thoroughly. +- Over-logging: avoid sensitive data exposure in logs. +- Churn hotspots imply the middleware may evolve; monitor for breaking changes. + +## Dependencies +- **request:** Used to access request data; must be used carefully to avoid blocking. +- **bodies:** For parsing request bodies if needed for logging (not shown explicitly here). +- **response:** For structured response data, if applicable. +- **status:** For standardized status code handling. +- **External logging library (implied):** Ensure logs are asynchronous and non-blocking. +- Use these dependencies according to their API contracts; avoid side effects or assumptions about their internal state. + +--- + +**Note:** Given the frequent modifications, always review recent changes for compatibility, especially around response lifecycle handling and logging formats. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_manages_payment_aeac3a11.md b/packages/app/server/src/AGENTS_manages_payment_aeac3a11.md new file mode 100644 index 000000000..aa744eb7f --- /dev/null +++ b/packages/app/server/src/AGENTS_manages_payment_aeac3a11.md @@ -0,0 +1,77 @@ +# Server Resources and Payment Handling Area + +## Purpose +Manages payment workflows, API key verification, video download handling, and facilitator proxy interactions within the server, ensuring secure access control and transaction creation for external payment providers and internal services. + +## Boundaries +- **Belongs:** + - API key validation (`verifyApiKey`) + - Video download request handling (`handleVideoDownload`) + - Payment transaction creation (`createPaidTransaction`, `createFreeTierTransaction`) + - Facilitator proxy communication (`facilitatorProxy`) + - Price and route modules (`prices.ts`, `route.ts`) + - Authentication headers (`headers.ts`) + - Balance checks (`BalanceCheckService.ts`) + - Metrics logging (`logMetric`) + - Graceful shutdown (`gracefulShutdown`) + - Operation ID extraction (`extractOperationId`) +- **Does NOT belong:** + - UI rendering or client-specific logic + - Core business logic unrelated to payments, video, or facilitator proxy + - External AI or model inference code + - Low-level HTTP request handling outside `fetchWithTimeout` + - Non-payment resource modules (e.g., unrelated data models) + +## Invariants +- `verifyApiKey()` must return `null` or a valid `ApiKeyValidationResult`; never throw or return undefined. +- `handleVideoDownload()` must validate headers and upstream URL before processing; must not proceed with invalid headers. +- All transaction creation methods (`createPaidTransaction`, `createFreeTierTransaction`) must ensure transactional integrity; do not proceed if prerequisites fail. +- `verifyAccessControl()` must be called before sensitive operations; must throw or reject if access is invalid. +- `extractOperationId()` must reliably parse operation IDs from request paths or names; invalid formats should throw or return empty string. +- `facilitatorProxy()` must handle retries or failures gracefully; must not silently swallow errors. +- `logMetric()` should be called with valid metric names and attributes; avoid logging sensitive info. +- `gracefulShutdown()` must clean up resources and reject new requests promptly. +- Null-safety: `extractVideoId()` and `extractOperationIdFromRequest()` should handle undefined or malformed inputs safely. +- External dependencies like `HttpError`, `UnauthorizedError`, `PaymentRequiredError` must be used consistently for error signaling. + +## Patterns +- Use `async/await` consistently for asynchronous operations. +- Validate all external inputs (`req`, `headers`, `body`) before processing. +- Use `extractOperationId()` and `extractOperationIdFromRequest()` to normalize operation identifiers. +- Wrap external calls (`fetchWithTimeout`, `facilitatorProxy`) with try/catch; propagate errors as `HttpError` derivatives. +- Log metrics with `logMetric()` after significant events (e.g., request received, transaction created). +- Enforce access control via `verifyAccessControl()` before transaction or resource modifications. +- Use specific error classes (`PaymentRequiredError`, `HttpError`, `UnauthorizedError`, `FacilitatorProxyError`) for error handling. +- Maintain clear separation between resource modules (`prices.ts`, `route.ts`) and core logic. +- Follow naming conventions: methods prefixed with `extract`, `verify`, `create`, `handle`, indicating their purpose. + +## Pitfalls +- **HttpError dependency:** Since `HttpError` is depended on by 7 external entities, modifications to its contract or inheritance can cause widespread issues. +- **Frequent churn areas:** `verifyApiKey`, `handleVideoDownload`, and resource modules (`prices.ts`, `route.ts`) change often; avoid making brittle assumptions about their structure. +- **Null/undefined handling:** `extractVideoId()` and `extractOperationIdFromRequest()` must handle malformed or missing data gracefully; failure can lead to runtime errors. +- **Churn-prone modules:** Prices and route modules are highly volatile; avoid tight coupling to specific versions. +- **Error propagation:** Failures in `facilitatorProxy()` or `fetchWithTimeout()` should be caught and transformed into appropriate `HttpError` subclasses. +- **Concurrency:** `incrementInFlightRequestsOrReject()` manages request concurrency; improper use can cause request rejection or deadlocks. +- **Metrics:** Ensure `logMetric()` calls do not leak sensitive data; validate attribute types. +- **Churn hotspots:** Be cautious when modifying `verifyApiKey()`, `handleVideoDownload()`, and related resource modules; changes may ripple through dependent systems. + +## Dependencies +- **External:** + - `AbortController` for request timeouts in `fetchWithTimeout`. + - `Router` for route handling. + - `call`, `convert`, `transaction`, `user` modules for core operations. +- **Internal:** + - `packages/app/server/src/resources/e2b/prices.ts`, `route.ts`, `tavily/prices.ts` for resource-specific logic; monitor for frequent updates. + - `packages/app/server/src/auth/headers.ts` for header management. + - `packages/app/server/src/services/facilitator/facilitatorProxy.ts` for facilitator communication; handle retries and error handling carefully. + - `packages/app/server/src/routers/common.ts` for utility functions like `extractOperationId`. + - `BalanceCheckService.ts` for balance validation. +- **Usage notes:** + - Always validate responses from `facilitatorProxy()` and `fetchWithTimeout()`. + - Use `verifyApiKey()` early in request handling to prevent unauthorized access. + - Maintain consistent error handling patterns with `HttpError` derivatives. + - When modifying resource modules, ensure compatibility with frequent churn patterns. + +--- + +This node encapsulates critical insights for AI agents to work effectively with the server's payment, resource, and proxy logic, emphasizing non-obvious invariants, patterns, and pitfalls to prevent regressions and ensure robust integrations. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_manages_refund_respo_c5eeb818.md b/packages/app/server/src/AGENTS_manages_refund_respo_c5eeb818.md new file mode 100644 index 000000000..73ebfd623 --- /dev/null +++ b/packages/app/server/src/AGENTS_manages_refund_respo_c5eeb818.md @@ -0,0 +1,42 @@ +# Refund Handler Module (packages/app/server/src/handlers/refund.ts) + +## Purpose +Manages refund response cleanup logic, specifically orchestrating response finalization and resource cleanup for refund-related API interactions. Ensures consistent cleanup procedures tied to refund responses, integrating with external response control functions. + +## Boundaries +- **Belongs here:** `setupResponseCleanup()` function, refund response lifecycle management, cleanup logic tied to refund responses. +- **Does NOT belong here:** Business logic for refund calculations, payment processing, or user account updates; these are outside the scope of response cleanup and should reside in dedicated modules. + +## Invariants +- `setupResponseCleanup()` must always invoke `close()` and `finish()` exactly once per response lifecycle. +- `res` (Response object) must be valid and open at the start; cleanup functions assume `res` is in a state suitable for `close()` and `finish()`. +- `userId`, `echoAppId`, `requestId` are non-null strings; used for logging, tracing, or cleanup context. +- Cleanup functions should not be called multiple times; idempotency is critical. +- The cleanup process must not throw exceptions that could disrupt the calling context; errors should be caught and logged internally. + +## Patterns +- Use `setupResponseCleanup()` as a dedicated pattern for response lifecycle management in refund flows. +- Follow naming conventions: functions prefixed with `setup` for initializers, `cleanup` for resource release. +- Ensure `close()` and `finish()` are called in the correct order if order matters; typically, `close()` before `finish()`. +- Pass all context parameters (`userId`, `echoAppId`, `requestId`) consistently for traceability. +- Handle errors within cleanup functions gracefully; do not let exceptions propagate. +- Use dependency injection or import references explicitly; avoid implicit globals. + +## Pitfalls +- Forgetting to call `close()` or `finish()` leads to resource leaks or hanging responses. +- Calling cleanup functions multiple times causes errors or inconsistent state. +- Chaining cleanup functions improperly, e.g., calling `finish()` before `close()`, may violate expected resource management contracts. +- Frequently modified (`5 versions`) functions like `setupResponseCleanup()` are prone to churn bugs; ensure thorough testing. +- External dependencies `close` and `finish` must be correctly imported; missing or incorrect imports cause runtime errors. +- Not handling errors within cleanup functions can crash the server or leave responses hanging. +- Avoid side effects in cleanup functions beyond response finalization; keep them idempotent and predictable. + +## Dependencies +- **External functions:** `close`, `finish` — must be imported correctly; understand their effects and side effects. +- **Response object (`res`):** must be a valid, open Response instance; ensure it is not already closed or finished before calling cleanup. +- **Context parameters (`userId`, `echoAppId`, `requestId`):** used for logging, tracing, or conditional cleanup logic; ensure they are validated before use. +- **No internal dependencies** are specified; rely solely on imported cleanup functions and response object. + +--- + +*Note:* When modifying `setupResponseCleanup()`, ensure idempotency, proper error handling, and adherence to response lifecycle contracts. Be cautious of frequent churn signals—test extensively after changes. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_manages_the_process_901a8c55.md b/packages/app/server/src/AGENTS_manages_the_process_901a8c55.md new file mode 100644 index 000000000..e7c654fb4 --- /dev/null +++ b/packages/app/server/src/AGENTS_manages_the_process_901a8c55.md @@ -0,0 +1,42 @@ +# Video URI Transformation in Server Package + +## Purpose +Manages the process of transforming video URIs within the server environment, specifically converting or processing video references using the `transformVideoUri` method and handling associated storage interactions. + +## Boundaries +- **Belongs here:** All logic related to URI transformation, storage referencing, and related data handling for videos. +- **Does NOT belong here:** UI rendering, client-side video handling, or unrelated data processing. Storage module implementations should reside elsewhere; only references are used here. + +## Invariants +- `transformVideoUri` must always await the completion of storage interactions before proceeding. +- The method should not mutate the input `video` object unless explicitly intended; side effects must be controlled. +- Storage dependency must be non-null and correctly initialized before invocation. +- URIs must be validated or sanitized before transformation; invalid URIs should trigger errors. +- The transformation process should maintain idempotency if called multiple times with the same inputs. +- Null or undefined `video` objects should be handled gracefully, with appropriate error propagation. +- The method must not leak resources or leave dangling references in storage. + +## Patterns +- Use consistent naming conventions: `transformVideoUri` clearly indicates transformation intent. +- Error handling should follow the established pattern: catch exceptions, log errors, and propagate as needed. +- Storage interactions should be abstracted via the `Storage` reference, respecting its interface. +- Asynchronous operations must use `await` to ensure proper sequencing. +- Churn-prone: modifications to `transformVideoUri` often involve URI parsing, storage updates, or error handling; ensure backward compatibility. + +## Pitfalls +- Frequent modifications to `transformVideoUri` suggest complexity; avoid introducing side effects or race conditions. +- Beware of null/undefined `video` objects; missing validation can cause runtime errors. +- Storage dependency must be correctly injected; incorrect or missing dependencies lead to failures. +- Do not assume URI validity; always validate before transformation. +- Avoid tight coupling with specific storage implementations; rely on the `Storage` interface. +- Churn hotspots indicate potential instability; test extensively after changes. +- Do not modify the `packages/app/server/src/__tests__/setup.ts` unless necessary; it may contain setup logic affecting test stability. + +## Dependencies +- **Storage:** Must be correctly instantiated and passed to `transformVideoUri`. Use the interface's methods reliably, respecting their expected behavior. +- External libraries (globally imported) should be used for URI validation or other auxiliary tasks, following established patterns. +- Ensure that any external dependencies used within `transformVideoUri` are compatible with asynchronous operations and error handling conventions. + +--- + +**Note:** Maintain strict adherence to the invariants and patterns to prevent regressions, especially given the high churn and frequent modifications in this code area. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_provides_core_fcd0f737.md b/packages/app/server/src/AGENTS_provides_core_fcd0f737.md new file mode 100644 index 000000000..e1784c778 --- /dev/null +++ b/packages/app/server/src/AGENTS_provides_core_fcd0f737.md @@ -0,0 +1,57 @@ +# Package: packages/app/server/src + +## Purpose +Provides core server-side utilities for user identification, environment configuration, storage initialization, URL construction, and updating user financial data within the application. Acts as a foundational layer supporting user-specific operations and external integrations. + +## Boundaries +- **Includes:** + - User ID retrieval (`getRequiredUserId`) + - Base URL generation (`getBaseUrl`) + - Storage setup (`initializeStorage`) + - Environment variable access (`getRequiredEnvVar`) + - User spending updates (`updateUserTotalSpent`) + - OpenAI provider module (`OpenAIBaseProvider.ts`) +- **Excludes:** + - Business logic beyond utility functions + - API route handlers, middleware, or request/response processing + - UI components or client-side code + - External API integrations beyond OpenAI provider module + - Data validation or serialization logic (handled elsewhere) + +## Invariants +- `getRequiredUserId()` must always return a non-empty string; it assumes prior authentication context is valid. +- `getBaseUrl(reqPath?)` must construct URLs consistently, respecting environment-specific base URLs; must handle optional `reqPath` gracefully. +- `initializeStorage()` must return a valid `Storage` instance or `null`; must not throw exceptions unexpectedly. +- `getRequiredEnvVar(name)` must throw if environment variable `name` is missing; guarantees environment-dependent configuration is present. +- `updateUserTotalSpent()` must be called within a Prisma transaction (`tx`) and must not violate transaction boundaries; `userId` must be valid, `amount` must be a Decimal, and updates should be atomic. + +## Patterns +- Use `getRequiredEnvVar()` for all environment-dependent configs; avoid hardcoded values. +- Always invoke `initializeStorage()` during startup; check for `null` before proceeding. +- When generating URLs via `getBaseUrl()`, pass specific request paths; ensure URL concatenation is correct and environment-aware. +- `getRequiredUserId()` should be called only after authentication; do not assume user context is present otherwise. +- Wrap `updateUserTotalSpent()` within a Prisma transaction; handle errors explicitly, avoid partial updates. +- Follow naming conventions: methods prefixed with `get` for retrieval, `initialize` for setup, `update` for mutations. + +## Pitfalls +- Frequent modifications to `getRequiredUserId()`, `getBaseUrl()`, `initializeStorage()`, `getRequiredEnvVar()`, and `updateUserTotalSpent()` indicate potential instability; agents must verify correctness after changes. +- Do not assume environment variables are always set; rely on `getRequiredEnvVar()` to enforce presence. +- `initializeStorage()` returning `null` requires null-checks; failing to do so may cause runtime errors. +- `updateUserTotalSpent()` must be called within a transaction; neglecting this risks data inconsistency. +- Be cautious with URL concatenation in `getBaseUrl()`, especially with trailing slashes or missing segments. +- Since these methods are frequently modified, avoid caching results unless explicitly invalidated, to prevent stale data. + +## Dependencies +- **Storage:** + - Used for persistent data management; must be initialized before use. + - Call `initializeStorage()` during startup; handle `null` case gracefully. +- **OpenAIBaseProvider.ts:** + - Provides base provider functionality for OpenAI API interactions; ensure correct import paths and configurations. +- **Environment Variables:** + - Critical for configuration; access via `getRequiredEnvVar()` to guarantee presence. +- **Prisma TransactionClient (`tx`):** + - Must be used for `updateUserTotalSpent()` to ensure atomicity; avoid external transaction management. + +--- + +**Note:** Always verify the latest version of methods after modifications, especially those marked as high-churn, to prevent regressions or inconsistencies. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_area_defines_ead39b3f.md b/packages/app/server/src/AGENTS_this_area_defines_ead39b3f.md new file mode 100644 index 000000000..43f40db79 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_area_defines_ead39b3f.md @@ -0,0 +1,45 @@ +# Error Handling and HTTP Error Classes in packages/app/server/src + +## Purpose +This area defines custom error classes for HTTP-related errors, primarily used to represent specific HTTP status conditions (e.g., 402 Payment Required, 401 Unauthorized, 503 FacilitatorProxyError, 400 Unknown Model, and generic status code errors). It standardizes error responses and facilitates consistent error handling across the server. + +## Boundaries +- **Belongs:** Custom error classes extending native Error, used throughout server request handling to signal specific HTTP errors. +- **Does NOT belong:** General application logic unrelated to HTTP errors; error handling for non-HTTP contexts; error serialization/deserialization outside error classes; external error handling middleware (unless explicitly integrated here). + +## Invariants +- Each error class must extend the native Error class. +- Constructor signatures must match the specified patterns, ensuring message consistency. +- For `constructor(statusCode: number, message: string)`, the statusCode must be stored as a property and used in error responses. +- Default messages should be used if no message argument is provided. +- Error instances should be properly initialized with message and, where applicable, statusCode. +- No error class should override the message property after construction. +- Error classes must be serializable if sent over network (e.g., include toJSON if needed). + +## Patterns +- Use default messages for constructors with no arguments. +- For HTTP status errors, ensure the status code is stored and accessible. +- Maintain consistent naming: `HttpPaymentRequiredError`, `HttpUnauthorizedError`, etc. +- Use async functions (e.g., `getBalance`) with explicit Promise return types. +- When creating new error instances, pass messages explicitly; avoid implicit error creation. +- Follow the pattern of defining error classes in `packages/app/server/src/errors/http.ts`. +- Error classes should be used in request validation, middleware, and service layers to propagate HTTP errors. + +## Pitfalls +- **Churn:** Constructor implementations are frequently modified; avoid relying on implicit behavior. +- **Null-safety:** Ensure message parameters are validated or defaulted; avoid passing undefined. +- **Error inheritance:** Forgetting to call `super()` with message can break stack traces. +- **Status code handling:** Misassigning or omitting `statusCode` in `constructor(statusCode, message)` leads to incorrect error responses. +- **Serialization:** Not implementing serialization methods may cause issues when errors are sent over HTTP. +- **Misuse of default messages:** Hardcoded defaults may become outdated; ensure they reflect current API semantics. +- **Churn hotspots:** Frequent modifications suggest these classes are sensitive; test error handling thoroughly. + +## Dependencies +- No external dependencies are directly imported or required for these error classes. +- Usage depends on consistent error handling middleware that interprets these error instances and converts them into HTTP responses. +- Ensure that the server's response layer correctly interprets `statusCode` and error message properties. + +--- + +**Summary:** +This cluster encapsulates custom HTTP error classes that standardize server error responses. Agents must understand the constructor patterns, invariants around message and statusCode handling, and the importance of consistent error serialization. Frequent modifications indicate these classes are central to error propagation; careful adherence to patterns and invariants is essential to prevent bugs and maintainability issues. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_area_manages_3bd42be3.md b/packages/app/server/src/AGENTS_this_area_manages_3bd42be3.md new file mode 100644 index 000000000..5fa8989f7 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_area_manages_3bd42be3.md @@ -0,0 +1,52 @@ +# Access Token Retrieval and Tracing Utilities + +## Purpose +This area manages obtaining Google OAuth access tokens via `getAccessToken()` and integrates tracing capabilities from `packages/app/server/src/utils/trace.ts`. It enables authenticated API calls and observability, crucial for secure interactions and debugging. + +## Boundaries +- **Belongs here:** + - Logic for acquiring and caching GoogleAuth tokens + - Trace initialization, span creation, and context propagation within `trace.ts` +- **Does NOT belong here:** + - Business logic unrelated to authentication or tracing (e.g., data processing, UI rendering) + - External API calls outside GoogleAuth scope + - Token storage or refresh mechanisms beyond `getAccessToken()` scope + - Trace configuration or setup code that isn't invoked within this module + +## Invariants +- `getAccessToken()` must always return a valid, non-expired token string; handle token refresh internally if needed. +- `getAccessToken()` must never return null, undefined, or an invalid token string. +- Tracing spans created via `trace.ts` must be correctly closed to avoid memory leaks. +- Trace context must propagate correctly across asynchronous boundaries to ensure accurate trace data. +- External `GoogleAuth` instance must be initialized before calling `getAccessToken()`. +- No assumptions about token cache invalidation timing; handle token expiry explicitly if caching is implemented. + +## Patterns +- Use `async/await` consistently for asynchronous operations in `getAccessToken()`. +- Error handling: propagate errors explicitly; do not swallow exceptions. +- Naming conventions: + - Method: `getAccessToken` (camelCase, verb-noun) + - Module: `trace.ts` (descriptive, lowercase with dots) +- Trace spans should be created with clear start/end boundaries, using context-aware APIs. +- External `GoogleAuth` should be imported and instantiated once; avoid re-initialization. +- Prefer explicit null/undefined checks over implicit truthiness. + +## Pitfalls +- Frequent modifications to `getAccessToken` increase risk of introducing token refresh bugs or caching issues. +- Mismanaging trace spans (not closing or propagating context) leads to incomplete traces. +- Relying on uninitialized `GoogleAuth` causes runtime errors. +- Forgetting to handle token expiry or refresh logic results in invalid tokens being used. +- External dependencies (GoogleAuth) may have version-specific behaviors; ensure compatibility. +- Churn in `trace.ts` suggests potential instability; avoid making unrelated changes that could break tracing. + +## Dependencies +- **GoogleAuth:** + - Use as a singleton; initialize once at module load. + - Ensure proper scope and credentials are configured before calling `getAccessToken()`. + - Handle potential errors during token fetch (e.g., network issues, permission errors). +- **trace.ts:** + - Use exported functions for span creation and context propagation. + - Maintain consistent trace context across async boundaries to preserve trace integrity. +- **Error Handling:** + - Fail gracefully; log errors without crashing. + - Consider retry logic if token fetch fails repeatedly. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_area_manages_4800216f.md b/packages/app/server/src/AGENTS_this_area_manages_4800216f.md new file mode 100644 index 000000000..bffa31ac9 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_area_manages_4800216f.md @@ -0,0 +1,37 @@ +# Gemini Stream Extraction and Completion State Interface + +## Purpose +This area manages the detection of Gemini stream requests via `extractGeminiIsStream` and defines the `CompletionStateBody` interface for handling completion state payloads. It enables the server to interpret specific request patterns and structure completion data accordingly. + +## Boundaries +- **Belongs here:** Logic for identifying Gemini stream requests (`extractGeminiIsStream`), data shape for completion states (`CompletionStateBody`). +- **Does NOT belong here:** Request parsing unrelated to Gemini streams, response formatting, or broader request handling logic; these should be handled in other modules or middleware. + +## Invariants +- `extractGeminiIsStream(req)` must reliably return `true` only if the request explicitly indicates a Gemini stream request, based on specific headers or parameters (not shown but implied). +- `CompletionStateBody` must accurately reflect the server's completion state; properties should be non-null unless explicitly optional. +- The interface should be stable; avoid adding or removing properties without versioning or clear migration paths. +- Null-safety: All non-optional properties must be initialized; optional properties may be omitted. +- No side effects: `extractGeminiIsStream` is a pure function, with no external state mutation. + +## Patterns +- Naming conventions: Use `extractGeminiIsStream` for request pattern detection; interface names should be descriptive (`CompletionStateBody`). +- Error handling: Assume `extractGeminiIsStream` returns `false` if request lacks required headers or parameters; do not throw exceptions. +- Interface design: Keep `CompletionStateBody` simple; avoid complex nested structures unless necessary. +- Versioning: Since both entities are frequently modified, document version changes explicitly; avoid breaking changes. + +## Pitfalls +- Frequent modifications to `extractGeminiIsStream` suggest potential instability; ensure all callers handle `false` gracefully. +- `CompletionStateBody` may evolve; avoid assumptions about property presence unless marked optional. +- Null safety: Missing null checks can cause runtime errors; enforce strict property initialization. +- Misinterpreting request signals: Rely on correct header/parameter checks within `extractGeminiIsStream`. +- Overloading the interface with optional properties can lead to inconsistent data handling. + +## Dependencies +- No external dependencies are directly used; however, `Request` must conform to expected structure (e.g., Express.js Request). +- Ensure request parsing (headers, query params) within `extractGeminiIsStream` aligns with server conventions. +- Maintain consistency with request and response handling patterns elsewhere in the codebase. + +--- + +**Note:** Given the high churn of both entities, document their version history and intended stability. Avoid making breaking changes without coordinated updates. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_area_manages_823347d1.md b/packages/app/server/src/AGENTS_this_area_manages_823347d1.md new file mode 100644 index 000000000..d64076504 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_area_manages_823347d1.md @@ -0,0 +1,45 @@ +# API Key Validation and Hashing + +## Purpose +This area manages API key validation and hashing mechanisms, enabling secure authentication by verifying API keys and generating hashes for storage or comparison. It encapsulates core logic for API key integrity and security. + +## Boundaries +- **Belongs here:** `validateApiKey` method, `hashApiKey` function, and related cryptographic operations within `BaseProvider.ts`. +- **Does NOT belong here:** User management, token issuance, or broader authentication flows outside API key validation. External token verification (e.g., JWT) is outside this scope unless integrated here. + +## Invariants +- `validateApiKey` must return `null` if the API key is invalid or malformed; never throw exceptions for invalid input. +- `hashApiKey` must produce consistent, deterministic hashes for identical input keys. +- Hashing must use `createHmac` with a secret key, ensuring cryptographic security. +- `validateApiKey` should rely on the hashed value comparison, not plaintext matching. +- Null safety: `apiKey` parameter in `validateApiKey` can be empty or null; handle gracefully. +- No side effects: `validateApiKey` should be idempotent and stateless. +- The `ApiKeyValidationResult` must accurately reflect validation status (valid, invalid, or null). + +## Patterns +- Use `createHmac` with a consistent secret key for hashing (`hashApiKey`). +- Always sanitize and validate `apiKey` input before processing. +- `validateApiKey` should perform secure comparison (constant-time if applicable) between stored hash and computed hash. +- Error handling: do not throw exceptions for validation failures; return `null` or result objects. +- Maintain naming conventions: `validateApiKey`, `hashApiKey`, and `ApiKeyValidationResult`. +- Modularize cryptographic logic to facilitate testing and potential replacement. + +## Pitfalls +- Churn: `validateApiKey` and `hashApiKey` are frequently modified; ensure backward compatibility when updating. +- Hashing errors: using inconsistent secrets or algorithms can invalidate validation. +- Null or empty `apiKey` inputs can cause false positives/negatives if not handled properly. +- Over-reliance on plaintext comparison; always compare hashes securely. +- External dependencies (`createHmac`, `jwtVerify`) must be correctly imported and used; misconfiguration can compromise security. +- Avoid exposing raw API keys or hashes in logs or error messages. +- Be cautious of timing attacks; use secure comparison methods if available. + +## Dependencies +- **createHmac**: cryptographic function from Node.js `crypto` module; use with a consistent secret key. +- **jwtVerify**: external JWT verification utility; ensure correct usage and key management if integrated. +- Properly manage secret keys used in `createHmac` to prevent leaks or mismatches. +- Do not hardcode secrets; fetch from secure environment variables or configuration. +- Validate dependency versions regularly to avoid vulnerabilities, especially for cryptographic functions. + +--- + +**Note:** Keep in mind that frequent modifications to `validateApiKey` and `hashApiKey` suggest evolving security requirements; ensure thorough testing and backward compatibility. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_area_manages_97cf148e.md b/packages/app/server/src/AGENTS_this_area_manages_97cf148e.md new file mode 100644 index 000000000..566ecabc1 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_area_manages_97cf148e.md @@ -0,0 +1,44 @@ +# Referral Reward Validation and Error Handling + +## Purpose +This area manages validation of referral reward data, parsing error responses from server interactions, and retrieving the base URL for API endpoints. It encapsulates core logic for ensuring referral reward integrity and consistent error processing. + +## Boundaries +- **Belongs here:** Validation logic for `ReferralRewardData`, error response parsing, and URL retrieval. +- **Does NOT belong here:** Business logic unrelated to referral rewards, UI rendering, or network request initiation. Data models (e.g., `ReferralRewardData`) should reside elsewhere; this code assumes their correctness. + +## Invariants +- `validateReferralReward` must always return a `ValidationResult` indicating success or failure; it cannot produce a null or undefined result. +- `parseErrorResponse` must handle all error body formats gracefully; it should not throw exceptions on malformed input. +- `getBaseUrl` must consistently return a non-empty string representing the API base URL; it should not return null or undefined. +- `validateReferralReward` should not mutate input data. +- Error parsing should respect the status code; certain errors may require different handling based on status. +- The `ValidationResult` must adhere to a contract: success indicated by a specific flag, errors by messages; this invariant must be preserved. + +## Patterns +- Use explicit null/undefined checks in `parseErrorResponse` to avoid runtime exceptions. +- Maintain consistent naming conventions: methods prefixed with verbs (`validate`, `parse`, `get`). +- Error responses should be parsed into a structured object, not raw strings. +- `validateReferralReward` should leverage existing validation utilities or rules; avoid duplicated logic. +- `getBaseUrl` should cache the result if it involves expensive computation or network calls. +- When modifying, preserve the method signatures and ensure backward compatibility with existing validation/error handling flows. + +## Pitfalls +- Frequent modifications to `validateReferralReward`, `parseErrorResponse`, and `getBaseUrl` increase risk of regressions; ensure thorough testing. +- Failing to handle malformed error bodies in `parseErrorResponse` can cause unhandled exceptions. +- Returning null or undefined from `getBaseUrl` violates invariants; always return a valid URL string. +- Overlooking the dependency on `ValidationResult` can lead to inconsistent validation outcomes. +- Churn in validation logic suggests evolving rules; document changes meticulously. +- Avoid side effects in validation and parsing methods; they should be pure functions. +- Be cautious of null-safety: `currentReferralReward` may contain null fields; validation should handle this gracefully. + +## Dependencies +- **ValidationResult:** Must be used consistently to communicate validation outcomes; ensure all validation methods produce a valid `ValidationResult`. +- **Decimal:** Used for precise numeric operations; avoid floating-point inaccuracies. +- External validation utilities or schemas should be used within `validateReferralReward` for consistency. +- Error response parsing should adhere to the expected server error formats; adapt parsing logic if server response schemas evolve. +- `ReferralRewardData` should be validated before passing into `validateReferralReward`, but this method should also perform internal validation as needed. + +--- + +*Note:* When modifying any method, verify that invariants hold, especially regarding return values and error handling. Maintain clear separation of concerns: validation, parsing, configuration retrieval. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_encapsu_93e48bad.md b/packages/app/server/src/AGENTS_this_cluster_encapsu_93e48bad.md new file mode 100644 index 000000000..089f2d44f --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_encapsu_93e48bad.md @@ -0,0 +1,51 @@ +# Semantic Cluster: Clients - Anthropic GPT Client + +## Purpose +This cluster encapsulates the logic for interfacing with the Anthropic GPT API, providing mechanisms to send requests (including streaming options) and parse server-sent events (SSE) data into structured image response formats. It enables the application to leverage Anthropic's language models for image generation tasks. + +## Boundaries +- **Belongs here:** + - `packages/app/server/src/clients/anthropic-gpt-client.ts` module, including `makeRequest` and `parseSSEImageGenerationFormat` functions. + - Handling of request configuration, streaming control, and SSE data parsing specific to Anthropic API responses. +- **Does NOT belong here:** + - Logic for other AI providers (e.g., OpenAI, other clients). + - UI rendering, user interaction, or frontend-specific code. + - Business logic unrelated to API communication or data parsing. + - Storage or persistence of generated images or responses. + +## Invariants +- `makeRequest` must always handle the `useStreaming` boolean explicitly; default is `false`. +- When streaming, `makeRequest` must correctly process SSE data chunks, ensuring no data loss or misordering. +- `parseSSEImageGenerationFormat` must only process valid SSE data strings; invalid or malformed data should be safely ignored or result in errors that do not crash the system. +- The `ImagesResponse[]` returned by `parseSSEImageGenerationFormat` must be ordered chronologically as received, preserving the sequence of image generation responses. +- Null or undefined responses from SSE data should be filtered out; the parser must not produce invalid `ImagesResponse` objects. +- External dependencies (like OpenAI) are imported but not directly used here; ensure correct versioning and compatibility. + +## Patterns +- Use explicit default parameters (`useStreaming = false`) in `makeRequest`. +- Implement robust error handling around SSE parsing to prevent partial or corrupted data from propagating. +- Follow naming conventions: functions prefixed with `parse` are pure data transformers; `makeRequest` manages network I/O. +- When modifying, ensure `makeRequest` manages resource cleanup (e.g., abort controllers if used). +- Maintain strict separation between request logic and data parsing functions. +- Use consistent data structures for `ImagesResponse[]` to facilitate downstream processing. + +## Pitfalls +- Churn hotspots indicate frequent modifications; avoid breaking existing request/response contracts. +- Mishandling streaming data can cause data corruption or incomplete image responses. +- Incorrect SSE parsing logic may lead to missed or malformed images, especially if data is not validated. +- Failing to handle null or malformed SSE data can cause runtime errors. +- Overlooking the importance of sequence order in responses may lead to UI inconsistencies. +- External dependencies like OpenAI must be correctly imported and versioned; mismatches can cause runtime failures. + +## Dependencies +- **External:** OpenAI SDK (imported but not directly used here). +- **Usage tips:** + - Use `makeRequest` with explicit `useStreaming` flag based on the context (e.g., streaming mode for real-time updates). + - When parsing SSE data with `parseSSEImageGenerationFormat`, ensure data strings are sanitized and validated before processing. + - Be aware of the API's SSE format specifics; adapt parsing logic if the server response format changes. + - Handle network errors and timeouts gracefully within `makeRequest`. + - Monitor the high-churn status to avoid regressions; test thoroughly after modifications. + +--- + +**Note:** This node captures deep, non-obvious knowledge critical for AI agents to modify, extend, or troubleshoot this code cluster effectively, emphasizing contracts, patterns, and pitfalls beyond the surface. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_encapsu_f23e8ac4.md b/packages/app/server/src/AGENTS_this_cluster_encapsu_f23e8ac4.md new file mode 100644 index 000000000..5d9cfd64d --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_encapsu_f23e8ac4.md @@ -0,0 +1,54 @@ +# Earnings Service and Sora-2 Client Semantic Cluster + +## Purpose +This cluster encapsulates the logic for requesting and processing earnings data via the `EarningsService` module, which relies on the `sora-2-client` for external API communication. It manages asynchronous data fetching, error handling, and data transformation specific to earnings-related endpoints. + +## Boundaries +- **Belongs here:** + - Data fetching logic for earnings, including request orchestration and response parsing. + - External API interactions via `sora-2-client`. + - Business logic related to earnings calculations or aggregations, if present. +- **Does NOT belong here:** + - UI rendering or presentation logic. + - Data persistence beyond transient API calls (e.g., database storage). + - Authentication, authorization, or session management—these are handled upstream or in other modules. + - Core application configuration unrelated to earnings API endpoints. + +## Invariants +- `makeRequest()` must always handle API errors gracefully, returning consistent error objects or nulls, never throwing unhandled exceptions. +- Responses from `sora-2-client` are assumed to be in a specific format; any deviation should trigger validation errors or fallback logic. +- All API requests initiated by `makeRequest()` are asynchronous; callers must await results to prevent race conditions. +- Null or undefined responses from external calls must be explicitly checked; no implicit assumptions about data presence. +- Resources such as network connections or tokens used by `sora-2-client` must be properly initialized before use and not leaked. + +## Patterns +- Use explicit async/await syntax for all external API calls within `makeRequest()`. +- Implement consistent error handling: catch exceptions, log errors, and return standardized error objects. +- Follow naming conventions: `makeRequest()` clearly indicates an API call; other functions should similarly be descriptive. +- Validate response schemas immediately after receiving data; reject or fallback if validation fails. +- Avoid side effects within `makeRequest()` beyond data fetching; keep it pure and predictable. +- Use dependency injection for `sora-2-client` to facilitate testing and mocking. + +## Pitfalls +- Frequent modifications to `EarningsService.ts`, `makeRequest()`, and `sora-2-client.ts` increase risk of regressions or inconsistent behavior. +- Improper error handling in `makeRequest()` can cause unhandled promise rejections or silent failures. +- Assumptions about external API response formats may lead to runtime errors if the API changes. +- Churned code may introduce race conditions if multiple concurrent requests are not properly managed. +- Over-reliance on external dependencies without validation can propagate malformed data downstream. +- Not adhering to the async pattern can cause deadlocks or unresponsive behavior. + +## Dependencies +- **OpenAI:** + - Used for generating or processing data related to earnings insights. + - Ensure API keys and rate limits are respected; handle OpenAI errors explicitly. +- **sora-2-client:** + - Encapsulates external API calls; must be initialized with correct credentials and endpoints. + - Use dependency injection to facilitate testing; avoid hardcoded instances. + - Validate responses immediately; handle network errors, timeouts, and malformed data robustly. +- **TypeScript types:** + - Maintain strict type safety for responses and request parameters to prevent runtime errors. + - Validate external data schemas before processing. + +--- + +**Note:** Always consider the high churn rate in these files; implement robust error handling, validation, and testing to mitigate regressions. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_0ca5d551.md b/packages/app/server/src/AGENTS_this_cluster_manages_0ca5d551.md new file mode 100644 index 000000000..afae4ff98 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_0ca5d551.md @@ -0,0 +1,40 @@ +# Semantic Cluster: Cleanup Process & Completion State + +## Purpose +This cluster manages the lifecycle of cleanup operations via `stopCleanupProcess()` and defines the `CompletionStateBody` interface for representing completion states. It enables controlled termination of cleanup routines and standardizes completion state data structures, ensuring predictable cleanup behavior. + +## Boundaries +- **Belongs here:** Implementation of cleanup routines, lifecycle management, and completion state data structures. +- **Does NOT belong here:** Core application logic unrelated to cleanup, unrelated state management, or UI components. Utility functions or external event handling should reside elsewhere. + +## Invariants +- `stopCleanupProcess()` must be idempotent: multiple calls should not cause errors or inconsistent states. +- It must only affect cleanup routines that are active; no side effects on unrelated processes. +- `CompletionStateBody` must be implemented with all required fields; partial implementations risk runtime errors. +- No null values should be assigned to non-nullable fields within `CompletionStateBody`. +- Cleanup process resources (e.g., timers, subscriptions) must be released or invalidated exactly once during `stopCleanupProcess()`. +- The method should not throw exceptions; handle all internal errors gracefully. + +## Patterns +- Naming: Use `stopCleanupProcess()` verbatim; avoid variations. +- Error handling: Fail silently or log internally; do not propagate exceptions. +- State checks: Before stopping cleanup, verify if cleanup is active to prevent redundant operations. +- Interface adherence: Implementers of `CompletionStateBody` should include explicit type annotations, avoid optional fields unless necessary. +- Churn awareness: `stopCleanupProcess()` and `CompletionStateBody` are frequently modified; document assumptions and invariants explicitly to prevent regressions. + +## Pitfalls +- **Frequent modifications:** Be cautious when editing `stopCleanupProcess()` and `CompletionStateBody`; ensure changes do not break existing contracts. +- **Resource leaks:** Forgetting to release resources in `stopCleanupProcess()` can cause leaks or dangling processes. +- **Null safety:** Assigning null to non-null fields in `CompletionStateBody` leads to runtime errors. +- **Concurrency issues:** If cleanup routines are asynchronous, race conditions may cause inconsistent states; synchronize access if needed. +- **Misuse of method:** Calling `stopCleanupProcess()` multiple times without idempotency checks can cause errors or inconsistent cleanup states. +- **Churn hotspots:** Changes to `stopCleanupProcess()` and `CompletionStateBody` are frequent; document behavior thoroughly. + +## Dependencies +- No external dependencies are explicitly required by this cluster. +- Ensure that any internal cleanup routines invoked within `stopCleanupProcess()` adhere to resource management best practices. +- If external modules or utilities are used for cleanup, verify they handle errors gracefully and are compatible with the idempotent nature of `stopCleanupProcess()`. + +--- + +**Note:** Maintain strict adherence to invariants and patterns, especially given the high churn. Regularly review for regressions related to cleanup idempotency and completion state integrity. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_114d484f.md b/packages/app/server/src/AGENTS_this_cluster_manages_114d484f.md new file mode 100644 index 000000000..073fdb64b --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_114d484f.md @@ -0,0 +1,48 @@ +# Semantic Cluster: URL Handling & Response Resolution (packages/app/server/src) + +## Purpose +This cluster manages URL base path resolution and response handling for server requests, ensuring consistent URL formation and response processing, especially for streaming and non-streaming data. + +## Boundaries +- **Belongs here:** + - `getBaseUrl(reqPath?)`: Constructs base URLs considering request context, environment, or configuration. + - `handleResolveResponse(res, isStream, data)`: Processes server responses, handling streaming vs. non-streaming data, including error handling and data parsing. +- **Does NOT belong here:** + - Routing logic, request dispatching, or middleware unrelated to URL resolution or response handling. + - Data storage, database interactions, or business logic beyond response processing. + - External API calls outside the scope of response handling. + +## Invariants +- `getBaseUrl(reqPath?)` must always produce a valid URL string, correctly concatenating base paths with optional request paths, respecting environment-specific base URLs. +- `handleResolveResponse(res, isStream, data)` must process responses without leaking resources; streams should be properly closed or piped, and errors must be caught and logged. +- When `isStream` is true, `data` is a stream; otherwise, it is a complete data object. +- Null or undefined `reqPath` in `getBaseUrl` should default to a known base URL. +- Response handling must not mutate the original response object. +- Response data must be processed in the correct order, especially when handling streams, to prevent data corruption or race conditions. + +## Patterns +- `getBaseUrl(reqPath?)` should use environment variables or configuration files to determine the base URL, appending `reqPath` safely. +- Consistent URL normalization: ensure no double slashes, proper encoding. +- `handleResolveResponse` should distinguish between stream and non-stream data via `isStream` flag, handling each case explicitly. +- Error handling: catch exceptions during response processing; log errors without throwing unless critical. +- Use of promise-based or async/await patterns for asynchronous response handling. +- Naming conventions: clear, descriptive method names; avoid ambiguous abbreviations. +- Maintain idempotency in response processing functions. + +## Pitfalls +- Frequent modifications to `getBaseUrl` suggest potential for inconsistent URL formation; ensure all versions adhere to the same pattern. +- Improper stream handling in `handleResolveResponse` can cause resource leaks or incomplete data delivery. +- Null or undefined `reqPath` handling in `getBaseUrl` may lead to malformed URLs if defaults are not set correctly. +- Race conditions or data corruption when processing streams asynchronously. +- Overlooking error cases in response handling, especially with streaming data. +- Churn hotspots indicate these methods are sensitive; avoid ad-hoc changes that break invariants. +- External dependencies are absent, but if added later, ensure they do not introduce side effects or break existing contracts. + +## Dependencies +- Currently, no external dependencies are used; ensure any future dependencies for URL parsing or response streaming are integrated following the patterns above. +- When handling streams, consider using standard libraries (e.g., Node.js `stream`) with proper error and close event handling. +- Environment variables or configuration objects should be accessed in `getBaseUrl` to maintain environment-specific URL formation. + +--- + +**Note:** This node emphasizes understanding the invariants and patterns critical for maintaining URL consistency and reliable response processing, especially given the high churn and frequent modifications. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_130feebf.md b/packages/app/server/src/AGENTS_this_cluster_manages_130feebf.md new file mode 100644 index 000000000..0677f2db9 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_130feebf.md @@ -0,0 +1,75 @@ +# Semantic Cluster: Server Resources and Transaction Creation + +## Purpose +This cluster manages HTTP route handlers for search and crawl functionalities under `resources/tavily`, and provides a core function `createE2BTransaction` for constructing transaction objects used in E2B (End-to-End Business) workflows. It encapsulates request routing, transaction instantiation, and proxy passthrough services, enabling coordinated data flow and external communication within the server. + +## Boundaries +- **Belongs here:** + - Route handlers for `/search` and `/crawl` endpoints, including request validation, parameter parsing, and response formatting. + - `createE2BTransaction`, which synthesizes transaction objects from input/output data and cost metrics, ensuring consistent transaction structure. + - `ProxyPassthroughService`, which facilitates proxying requests or data passthrough, assuming it handles external API interactions or middleware logic. +- **Does NOT belong here:** + - Business logic unrelated to request routing or transaction creation (e.g., core crawling algorithms, search indexing). + - Data persistence layers or database access code. + - Authentication, authorization, or user session management (unless integrated directly into route handlers). + - External API client implementations—these should be abstracted or injected. + +## Invariants +- `createE2BTransaction` must always produce a valid `Transaction` object with non-null `input`, `output`, and `cost`. +- The `cost` parameter passed to `createE2BTransaction` must be a `Decimal` type, and its value should be validated before invocation. +- Route handlers should validate request parameters strictly; invalid requests must return proper HTTP error responses. +- `ProxyPassthroughService` should not perform side effects outside its scope; it must handle errors gracefully, returning appropriate error responses. +- The `Transaction` reference used in the cluster must be consistent; modifications to its structure or lifecycle are restricted to ensure data integrity across components. +- Frequently modified files (`route.ts`, `createE2BTransaction`) imply high churn; changes should be reviewed for side effects on request flow and transaction consistency. + +## Patterns +- Route handlers should follow a pattern of: + - Extracting parameters from request objects. + - Validating parameters explicitly. + - Calling core functions (`createE2BTransaction`) with sanitized data. + - Returning responses with proper status codes. +- `createE2BTransaction` should: + - Enforce that `input` and `output` are non-null. + - Use consistent naming conventions for parameters and returned object fields. + - Handle edge cases where input data may be incomplete or malformed. +- Error handling: + - Use try-catch blocks around external or risky operations. + - Log errors with context-specific messages. + - Return standardized error responses. +- Naming conventions: + - Use descriptive, context-specific names for route parameters, request bodies, and transaction fields. + - Maintain consistent casing and formatting across modules. + +## Pitfalls +- **Churn-related risks:** + - Frequent modifications to route files and `createE2BTransaction` increase risk of breaking request flow or transaction integrity. + - Changes in transaction structure may cause downstream issues if not propagated properly. +- **Coupling hazards:** + - Tight coupling between route handlers and `Transaction` references can lead to brittle code if `Transaction` shape evolves. + - `ProxyPassthroughService` may introduce external dependencies; improper use can cause latency or error propagation. +- **Null-safety and validation:** + - Failing to validate request parameters can lead to null dereferences or invalid transactions. + - Assumptions about `cost` being a `Decimal` must be enforced; improper input types can cause runtime errors. +- **Error handling:** + - Not catching errors in `createE2BTransaction` or route handlers may result in unhandled promise rejections or server crashes. +- **High churn files:** + - Frequent updates to route files suggest evolving API contracts; agents must verify compatibility and test thoroughly after modifications. + +## Dependencies +- **Transaction:** + - Core data structure; must be used consistently when creating or manipulating transactions. + - Ensure any updates to `Transaction` shape are reflected in `createE2BTransaction` and route handlers. +- **External libraries (implied):** + - Decimal library for `cost` parameter; validate and handle conversions explicitly. + - HTTP framework (e.g., Express) for route definitions; follow framework conventions for middleware and error handling. +- **`ProxyPassthroughService`:** + - Use as an abstraction for external API calls or data forwarding. + - Handle errors internally; do not assume external services are always available. +- **Request validation libraries (if used):** + - Enforce strict parameter validation to prevent invalid data from propagating. +- **Logging and error reporting:** + - Implement consistent logging for traceability, especially around high-churn files. + +--- + +**Note:** Given the high modification frequency of key files, agents should implement rigorous testing and validation procedures after each change to maintain stability and correctness. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_17eb35b0.md b/packages/app/server/src/AGENTS_this_cluster_manages_17eb35b0.md new file mode 100644 index 000000000..1eac8ee4d --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_17eb35b0.md @@ -0,0 +1,55 @@ +# Semantic Cluster: Code Interaction with GroqProvider and Gemini Client + +## Purpose +This cluster manages server-side data fetching via `GroqProvider` and `gemini-client`, enabling structured requests and responses. It encapsulates request construction, streaming, and client communication, forming the backbone of data layer interactions. + +## Boundaries +- **Belongs:** + - `GroqProvider.ts`: Request logic, streaming control, request lifecycle management. + - `makeRequest()`: Handles request initiation, streaming toggle, and response handling. + - `gemini-client.ts`: Client implementation, API communication, connection management. +- **Does NOT belong:** + - UI rendering, user interaction, or presentation logic. + - Authentication, authorization, or user session management (unless embedded in request headers). + - Data persistence beyond request/response cycle (e.g., database operations). + - External API integrations outside of Gemini client unless explicitly wrapped here. + +## Invariants +- `makeRequest()` must always resolve with a valid response or throw an error; never silently fail. +- When `useStreaming` is true, `makeRequest()` must handle partial data streams correctly, ensuring no data loss or corruption. +- `GroqProvider` must maintain idempotency: repeated calls with same parameters should not cause side effects or inconsistent states. +- All network requests should include proper error handling, retries, or fallback logic as per the code pattern. +- External dependencies like GoogleGenAI should be used within their intended API contracts, respecting rate limits and data formats. + +## Patterns +- Use consistent naming conventions: `makeRequest()` for request functions, `GroqProvider` for provider modules. +- Error handling follows try-catch blocks; propagate errors explicitly. +- Streaming mode toggled via boolean parameter; ensure correct setup of streaming handlers. +- Request lifecycle: initialize → send → handle response/error → cleanup. +- Modular separation: request logic in `GroqProvider`, client communication in `gemini-client`. +- Use async/await for asynchronous flows; avoid callback hell. +- Document assumptions about request parameters and response formats explicitly. + +## Pitfalls +- Frequent churn in `GroqProvider.ts`, especially around request construction and streaming logic, risks regressions. +- `makeRequest()`'s default `useStreaming=false` may be overlooked, causing inconsistent data handling. +- External dependency misusage: improper rate limiting or ignoring API contract changes in GoogleGenAI. +- Potential resource leaks if streaming handlers or request cancellations are not properly managed. +- Coupling between `GroqProvider` and Gemini client may lead to brittle integrations if API schemas evolve. +- Churn hotspots suggest high modification frequency; avoid assumptions about internal implementation stability. + +## Dependencies +- **GoogleGenAI:** + - Use according to API documentation; respect rate limits and data formats. + - Handle errors gracefully; implement retries if needed. +- **gemini-client:** + - Ensure connection lifecycle management aligns with request patterns. + - Use the client’s API as documented; avoid assumptions about internal state. +- **TypeScript types:** + - Maintain strict type safety; validate request/response schemas explicitly. +- **Logging/Monitoring:** + - Instrument request lifecycle events for observability, especially around high-churn modules. + +--- + +**Note:** Agents modifying this cluster should pay close attention to the high-churn modules, especially around request handling and streaming logic, to prevent regressions and ensure robustness. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_1e736bc2.md b/packages/app/server/src/AGENTS_this_cluster_manages_1e736bc2.md new file mode 100644 index 000000000..844c7ab5d --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_1e736bc2.md @@ -0,0 +1,49 @@ +# Echo App and User GCS URI Management + +## Purpose +This cluster manages retrieval of EchoApp entities by ID and constructs Google Cloud Storage URIs for user-specific data, enabling consistent access patterns and data referencing within the server. + +## Boundaries +- **Belongs here:** + - Retrieval of EchoApp data via `getEchoAppById`. + - Construction of user-specific GCS URIs via `buildUserGcsUri`. +- **Does NOT belong here:** + - Data persistence logic for EchoApp (handled elsewhere). + - Authentication, authorization, or access control. + - GCS bucket configuration or environment setup. + - Other resource URI schemes or cloud storage providers. + +## Invariants +- `getEchoAppById` must return `null` if no matching EchoApp exists; never throw or return undefined. +- `buildUserGcsUri` must encode `userPath` with `encodeURIComponent` to ensure URI safety. +- The constructed URI from `buildUserGcsUri` should always follow a consistent pattern, e.g., `gs:////`. +- User IDs and paths used in `buildUserGcsUri` must be validated for non-empty, non-null strings before invocation. +- `getEchoAppById` should cache results if used frequently, but cache invalidation is outside this scope. +- No side effects are expected; methods are pure or rely solely on provided parameters. + +## Patterns +- Use `encodeURIComponent` for all userPath segments in `buildUserGcsUri`. +- Handle null or invalid `echoAppId` gracefully, returning `null` if not found. +- Follow consistent naming conventions: `getEchoAppById`, `buildUserGcsUri`. +- Maintain asynchronous pattern in `getEchoAppById`; ensure proper await/async handling. +- Document assumptions about `EchoApp` shape externally; code assumes existence of such type. +- Avoid side effects; methods should be deterministic given inputs. +- Use explicit null checks and validation for input parameters. + +## Pitfalls +- **Frequent modifications** of both methods suggest instability; avoid assumptions about their internal logic. +- **Null safety:** `getEchoAppById` may return `null`; callers must handle this. +- **URI encoding:** Failing to encode `userPath` in `buildUserGcsUri` risks invalid URIs. +- **Parameter validation:** Passing empty or malformed IDs/paths can produce invalid results. +- **Churn risk:** Changes in URI structure or EchoApp retrieval logic may break downstream consumers. +- **No dependency on external cache or state:** Rely solely on parameters; avoid implicit dependencies. +- **Concurrency considerations:** If used in high-concurrency contexts, ensure thread safety if caching is introduced later. + +## Dependencies +- **encodeURIComponent:** Use correctly to encode `userPath` segments in `buildUserGcsUri`. +- No external dependencies are explicitly required for `getEchoAppById`; assume database or data source access is abstracted. +- Ensure environment provides necessary configuration for URI construction (e.g., bucket name), if applicable, outside this scope. + +--- + +**Note:** Always verify that `getEchoAppById` handles errors internally or propagates exceptions appropriately. For `buildUserGcsUri`, confirm that inputs are sanitized before use to prevent injection or malformed URIs. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_34b60515.md b/packages/app/server/src/AGENTS_this_cluster_manages_34b60515.md new file mode 100644 index 000000000..091a13eb7 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_34b60515.md @@ -0,0 +1,51 @@ +# Semantic Cluster: Video Response & Referral Code Handling + +## Purpose +This cluster manages extraction of video data from generic response objects, parsing provider identifiers from response bodies, and retrieving user-specific referral codes asynchronously. It encapsulates response parsing logic and user data retrieval, serving as a bridge between raw API responses and application-specific data models. + +## Boundaries +- **Belongs here:** + - Response data parsing (`extractVideosFromResponse`, `parseProviderIdFromResponseBody`) + - User referral code retrieval (`getReferralCodeForUser`) + - Handling of raw API responses and user IDs as input parameters +- **Does NOT belong here:** + - API request logic (e.g., HTTP calls, request retries) + - UI rendering or presentation logic + - Data storage or caching mechanisms outside of transient processing + - External SDK integrations unless explicitly imported (none here) + +## Invariants +- `extractVideosFromResponse` must return `null` if response data lacks expected video structures; never return undefined. +- `parseProviderIdFromResponseBody` must always return a string; if parsing fails, throw or return empty string (preferably throw to signal parse failure). +- `getReferralCodeForUser` must resolve to `null` if user ID or echoAppId are invalid or if the referral code isn't available; never reject promise unless critical error occurs. +- All methods should handle unexpected data gracefully, avoiding unhandled exceptions. +- Response parsing functions should not mutate input data. +- `extractVideosFromResponse` should process only the relevant parts of `responseData`, ignoring unrelated fields. +- `parseProviderIdFromResponseBody` assumes the response body contains a recognizable provider ID; if not, it must handle missing or malformed data explicitly. +- `getReferralCodeForUser` relies on external data sources; ensure proper await handling and error catching in calling code. + +## Patterns +- Use explicit null checks and type guards when parsing untyped response data. +- Maintain consistent naming: `extractVideosFromResponse`, `parseProviderIdFromResponseBody`, `getReferralCodeForUser`. +- Error handling: throw on parse failures; resolve with null or empty string as appropriate for missing data. +- Asynchronous functions (`getReferralCodeForUser`) should always return a Promise; handle rejections internally if possible, or document rejection scenarios clearly. +- Avoid side effects; these methods are pure or semi-pure data transformers. +- Document expected response shapes, especially for `responseData` and `data` in `parseProviderIdFromResponseBody`. + +## Pitfalls +- Frequent modifications to `extractVideosFromResponse`, `parseProviderIdFromResponseBody`, and `getReferralCodeForUser` increase risk of regressions; ensure thorough tests accompany changes. +- Null-safety: failing to check for missing or malformed response fields can cause runtime errors. +- Churn hotspots indicate these methods are sensitive to API response schema changes; monitor for API updates. +- Misuse of `parseProviderIdFromResponseBody` without proper error handling can lead to silent failures or incorrect provider IDs. +- `getReferralCodeForUser` may depend on external systems; improper error handling or assumptions about data availability can cause bugs. +- Avoid assuming response data shapes; always validate before access. +- Do not introduce side effects or state mutations within these methods. + +## Dependencies +- No external dependencies are explicitly imported; however, if integrated with external APIs or SDKs in the broader codebase, ensure correct usage patterns. +- When extending or modifying `getReferralCodeForUser`, verify external data source reliability and handle potential network errors gracefully. +- For response parsing functions, rely solely on the provided input data; no external parsing libraries are needed here. + +--- + +**Note:** Keep in mind that these methods are frequently modified, so maintain clear version control and comprehensive tests to prevent regressions. Ensure that any schema assumptions are validated at runtime to avoid silent failures. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_38fbd499.md b/packages/app/server/src/AGENTS_this_cluster_manages_38fbd499.md new file mode 100644 index 000000000..b46efc476 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_38fbd499.md @@ -0,0 +1,64 @@ +# Semantic Cluster: Server Request Handling and Proxy Logic + +## Purpose +This cluster manages incoming API requests, particularly for AI model transactions, handling authorization, cost calculation, proxying, and route-specific logic. It encapsulates the core flow for resource requests, escrow setup, and passthrough proxy handling within the server, ensuring correct cost enforcement and request validation. + +## Boundaries +- **Belongs here:** Request parsing (`handleBody`, `extractModelName`), cost calculations (`getModelPrice`, `applyMaxCostMarkup`), proxy requests (`makeProxyPassthroughRequest`, `detectPassthroughProxyRoute`), route validation (`isOperationsPath`, `isApiRequest`), escrow context setup (`setupEscrowContext`), request handling orchestration (`handleResourceRequest`, `settle`), request authentication (`authenticateRequest`), and provider initialization (`initializeProvider`). +- **Does NOT belong here:** Business logic for specific models (e.g., model training, fine-tuning), detailed provider implementations (VertexAIProvider, GeminiVeoProvider), UI components, or database schema definitions. Those are in other modules/services. + +## Invariants +- `handleBody` must parse and validate the request body before proceeding. +- Cost calculations (`getRequestMaxCost`, `applyMaxCostMarkup`) must respect the maximum allowed cost; exceeding should trigger errors or rejection. +- Proxy requests (`makeProxyPassthroughRequest`) must include processed headers and match route detection (`detectPassthroughProxyRoute`) to avoid misrouting. +- `setupEscrowContext` must be called before any transaction or cost deduction. +- `authenticateRequest` must be invoked before processing sensitive operations; failure halts further processing. +- `handleApiRequest` and `handleResourceRequest` must handle errors gracefully, returning appropriate HTTP status codes. +- `isValidModel`, `isValidImageModel`, `isValidVideoModel` enforce model name validation; invalid models should trigger `UnknownModelError`. +- `getModelPrice`, `getImageModelPrice`, `predictMaxVideoCost` must align with provider pricing data; mismatches can cause cost miscalculations. +- `TransactionEscrowMiddleware` must not leak resources or leave inconsistent state; must always finalize escrow setup. +- `setMaxCostMarkup` must not produce negative or nonsensical values. +- All request handlers must respect the `isPassthroughProxyRoute` flag to avoid route conflicts. +- External dependencies like `PrismaClient`, `Blob`, `Decimal` should be used with their respective safety and precision guarantees. + +## Patterns +- Use `extractModelName`, `extractGeminiModelName`, and `detectPassthroughProxyRoute` for route and model extraction, following naming conventions. +- Always validate models with `isValidModel`, `isValidImageModel`, `isValidVideoModel` before use. +- Wrap API resource handling with `handleResourceRequest` or `handle402Request` to standardize error handling. +- Use `setupEscrowContext` immediately after authentication to initialize transaction context. +- For cost calculations, leverage `calculateActualCost`, `calculateMaxCost`, and `applyMaxCostMarkup` in sequence, ensuring cost limits are enforced. +- When proxying, use `makeProxyPassthroughRequest` with `processedHeaders` to preserve request integrity. +- Follow the pattern of checking route type (`isOperationsPath`, `detectPassthroughProxyRoute`) before processing. +- Use `handleInFlightRequestIncrement` to track ongoing requests, especially in high concurrency environments. +- Maintain consistent error handling: throw `HttpError`, `UnauthorizedError`, or custom errors like `UnknownModelError` as needed. +- Use `initializeProvider` for setting up providers dynamically based on request context. + +## Pitfalls +- **Churn-prone code:** `constructor`, `getType`, `handleBody`, `formatUpstreamUrl`, `handleApiRequest` are frequently modified; avoid breaking invariants during updates. +- **High coupling:** Many functions depend on external modules and services (`ProviderInitializationService`, `EchoControlService`, `Transaction`), increasing integration risk. +- **Route detection errors:** `detectPassthroughProxyRoute` and `isOperationsPath` are critical; incorrect detection leads to misrouted requests. +- **Cost miscalculations:** `getModelPrice`, `getImageModelPrice`, `predictMaxVideoCost` must be synchronized with provider pricing; discrepancies cause billing issues. +- **Model validation:** `isValidModel` and related functions must be kept current; invalid models bypass validation, risking errors downstream. +- **Frequent modifications:** Core functions like `handleApiRequest`, `handleBody`, and `settle` are hot spots; changes can introduce subtle bugs. +- **Resource leaks:** Middleware like `TransactionEscrowMiddleware` must ensure cleanup; failure leads to dangling transactions. +- **Proxy headers:** `processedHeaders` must be correctly constructed; malformed headers can cause security or routing issues. +- **Concurrency:** `handleInFlightRequestIncrement` must be used carefully to avoid race conditions or request drops. +- **Error handling:** Always handle errors from external dependencies (`PrismaClient`, `Blob`, `Decimal`) to prevent crashes. +- **Cost enforcement:** Never skip `getRequestMaxCost` or `applyMaxCostMarkup`; ignoring limits risks overbilling. + +## Dependencies +- **Core modules:** `PrismaClient`, `Transaction`, `BaseProvider`, `EchoControlService`, `HttpError`, `UnauthorizedError`, `UnknownModelError`. +- **Request/Response:** `Request`, `Response`, `EscrowRequest`. +- **Utilities:** `calculateActualCost`, `calculateMaxCost`, `Decimal`, `Blob`, `FormData`. +- **Routing & URL:** `formatUpstreamUrl`, `detectPassthroughProxyRoute`, `isOperationsPath`, `isApiRequest`. +- **Provider & Model validation:** `isValidModel`, `isValidImageModel`, `isValidVideoModel`, `getModelPrice`, `getImageModelPrice`, `predictMaxVideoCost`. +- **Authentication & Security:** `authenticateRequest`, `X402AuthenticationService`. +- **Resource handling:** `handleResourceRequest`, `handle402Request`, `settle`. +- **Provider initialization:** `initializeProvider`. +- **Error handling:** `HttpError`, `UnauthorizedError`, `UnknownModelError`. +- **Logging & Metrics:** `logMetric`, `buildX402Response`. +- **Proxy & passthrough:** `makeProxyPassthroughRequest`, `detectPassthroughProxyRoute`. + +--- + +This dense, actionable knowledge base ensures AI agents understand the critical invariants, patterns, and pitfalls in this request handling cluster, enabling robust, consistent modifications aligned with existing architecture. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_39959e99.md b/packages/app/server/src/AGENTS_this_cluster_manages_39959e99.md new file mode 100644 index 000000000..0b0f7038b --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_39959e99.md @@ -0,0 +1,54 @@ +# Semantic Cluster: Server Utilities and Telemetry Integration + +## Purpose +This cluster manages server-side operational functions, including cleanup routines, telemetry metrics, and environment configuration. It ensures resource management, error reporting, and model identification are handled consistently, integrating with OpenTelemetry for observability. + +## Boundaries +- **Includes:** + - Cleanup interval management (`clearInterval`) + - Telemetry metric logging (`logMetric`) + - Model name retrieval (`getModel`) + - Environment configuration (`env.ts`) + - Logging setup (`logger.ts`) +- **Excludes:** + - Business logic unrelated to server maintenance or telemetry + - Client-side code + - External API integrations outside telemetry and environment setup + - Data persistence or database interactions + +## Invariants +- `clearInterval(this.cleanupInterval)` must be called exactly once during cleanup; repeated calls or omission can cause resource leaks or errors. +- `logMetric` must always include an `error_message` property; if `error` is not an `Error`, default to `'unknown'`. +- `getModel()` must return a consistent string identifier; it should not return null or undefined. +- Environment variables accessed via `createEnv()` are assumed to be correctly set; missing or malformed variables may cause failures. +- Telemetry exporters (`OTLPLogExporter`, `OTLPMetricExporter`) must be initialized before use; their absence leads to silent metrics/logs loss. +- The telemetry setup (imported modules) assumes proper configuration and network connectivity; misconfiguration can silently degrade observability. + +## Patterns +- Use `logMetric` with a fixed metric name `'escrow.cleanup_failed'` for error reporting; always include error details. +- Use `clearInterval` with a stored interval ID (`this.cleanupInterval`) to manage periodic cleanup tasks. +- `getModel()` should be a simple accessor returning a string; avoid complex logic or side effects. +- Environment variables should be loaded once via `createEnv()` and cached if needed. +- Logging should utilize `LoggerProvider` consistently; avoid direct console logs. +- Telemetry setup involves `OTLPLogExporter`, `OTLPMetricExporter`, and `PeriodicExportingMetricReader`; follow their initialization patterns precisely. + +## Pitfalls +- Frequent modifications to `clearInterval`, `logMetric`, and `getModel` suggest potential instability; ensure changes are tested thoroughly. +- Forgetting to clear intervals can cause memory leaks or duplicate executions. +- Improper error message handling in `logMetric` can obscure root causes. +- Relying on environment variables without validation risks runtime failures. +- Telemetry exporters require correct network configuration; misconfiguration leads to silent data loss. +- Changes in dependencies (e.g., `LoggerProvider`, `MeterProvider`) may break observability; monitor for updates. +- Churn in environment and logger modules indicates configuration drift; verify settings after updates. + +## Dependencies +- **LoggerProvider:** Use for consistent logging; initialize once, avoid re-instantiation. +- **MeterProvider & OTLPMetricExporter:** For metrics; ensure network and endpoint configurations are correct. +- **OTLPLogExporter & PeriodicExportingMetricReader:** For log exporting; initialize before use, handle export errors. +- **OpenTelemetryTransportV3 & traceContextFormat:** For trace context propagation; follow setup patterns to maintain trace continuity. +- **createEnv & resourceFromAttributes:** For environment configuration; validate environment variables at startup. +- **External modules (`LoggerProvider`, `MeterProvider`, etc.):** Use according to their API contracts; handle initialization errors gracefully. + +--- + +**Summary:** This cluster encapsulates server maintenance routines and observability setup, requiring careful resource management, error handling, and adherence to telemetry configuration patterns. Frequent churn signals the need for rigorous testing and validation when modifying these entities. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_3d996aca.md b/packages/app/server/src/AGENTS_this_cluster_manages_3d996aca.md new file mode 100644 index 000000000..aaf385dfe --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_3d996aca.md @@ -0,0 +1,62 @@ +# Semantic Cluster: Transaction and Pricing Handling (packages/app/server/src) + +## Purpose +This cluster manages transaction processing, request formatting, and cost calculations related to tools and escrow, serving as the core logic for transaction cost estimation, request parsing, and response streaming within the server. + +## Boundaries +- **Belongs here:** + - Methods for extracting user identity (`getUserId`) + - Request body formatting (`formatRequestBody`) + - Handling raw transaction data (`handleBody`) + - Parsing SSE responses (`parseSSEResponsesFormat`) + - Cost application logic (`applyEchoMarkup`) + - Cost computation (`computeTransactionCosts`, `predictMaxToolCost`) +- **Does NOT belong here:** + - UI rendering or client-side request initiation + - Authentication middleware or user session management + - External API integrations unrelated to pricing or transaction processing + - Data persistence beyond transient computations (e.g., database storage) + +## Invariants +- `getUserId()` must return `null` if no user is authenticated; never throw exceptions. +- `formatRequestBody()` must include all necessary headers and correctly serialize the request; headers are immutable post-call. +- `handleBody()` must parse `data` into a valid `Transaction` object; invalid data should trigger specific error handling, not silent failures. +- `parseSSEResponsesFormat()` must produce a complete, ordered list of `ResponseStreamEvent` objects; responses are assumed to be well-formed, but malformed data must be gracefully handled. +- `applyEchoMarkup()` should only modify the `cost` when `cost` is a valid `Decimal`; avoid side effects. +- `computeTransactionCosts()` must correctly incorporate `referralCodeId` and `addEchoProfit`; cost calculations depend on `getCostPerToken` and `LlmTransactionMetadata`. +- `predictMaxToolCost()` relies on `req` and `provider` being valid; must not produce negative costs or throw unhandled errors. +- All cost functions should respect the `Decimal` precision and avoid floating-point inaccuracies. + +## Patterns +- Use consistent naming conventions: `getUserId`, `formatRequestBody`, `handleBody`, etc. +- Error handling: propagate errors explicitly; do not swallow exceptions silently. +- When modifying `cost`, use `applyEchoMarkup()` to ensure markup logic is centralized. +- Asynchronous functions (`async`) should always await dependencies and handle potential rejections. +- Cost calculation functions (`calculateToolCost`, `predictMaxToolCost`) should cache results if called repeatedly with identical inputs. +- Use dependency injection for `BaseProvider` and `Request` objects to facilitate testing and mocking. +- Maintain null-safety: `getUserId()` may return `null`; downstream code must handle this case explicitly. +- When parsing responses (`parseSSEResponsesFormat`), validate data structure before processing to prevent runtime errors. + +## Pitfalls +- Frequent modifications to `getUserId`, `formatRequestBody`, `handleBody`, `parseSSEResponsesFormat`, and `applyEchoMarkup` indicate high churn; changes here risk breaking assumptions about request/response formats. +- Null handling in `getUserId()` is critical; incorrect assumptions can lead to unauthorized actions or null dereferences. +- Cost calculation functions depend on external `getCostPerToken`; incorrect or stale values may cause mispricing. +- `computeTransactionCosts()` involves multiple parameters; improper use of `referralCodeId` or `addEchoProfit` can produce inconsistent costs. +- `predictMaxToolCost()` relies on `provider` and `req`; misconfiguration or invalid inputs can yield negative or nonsensical costs. +- SSE response parsing (`parseSSEResponsesFormat`) is sensitive to data format; malformed data can cause unhandled exceptions if not validated. +- High churn in core methods suggests frequent API or data format changes; agents should monitor version history and deprecate old patterns carefully. + +## Dependencies +- **References:** + - `LlmTransactionMetadata`, `Transaction`, `Tool`, `EscrowRequest`, `BaseProvider` — ensure these types are correctly instantiated and validated before use. +- **Calls:** + - `getCostPerToken` — use with awareness of current pricing models; cache results if possible. + - `UnauthorizedError` — handle explicitly to prevent silent failures during auth failures. +- **External Imports:** + - `Decimal` — use for all monetary calculations; avoid floating-point inaccuracies. + - `high` — (assumed to be a utility or constant); verify its purpose and usage context. + +--- + +**Note:** +Agents should treat this cluster as a critical, high-churn core responsible for transaction integrity and cost accuracy. Changes require careful validation, especially around null safety, data parsing, and cost calculations. Proper dependency management and error handling are essential to prevent subtle bugs. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_4b9124d8.md b/packages/app/server/src/AGENTS_this_cluster_manages_4b9124d8.md new file mode 100644 index 000000000..830efeed1 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_4b9124d8.md @@ -0,0 +1,66 @@ +# Semantic Cluster: Providers and Stream Handling (packages/app/server/src) + +## Purpose +This cluster manages provider abstractions for various AI services (OpenAI, VertexAI, Gemini, Anthropic, XAI, Groq, etc.), focusing on request/response transformation, stream support, and URL signing. It encapsulates provider-specific logic, ensuring consistent interfacing, especially around streaming data and model pricing. + +## Boundaries +- **Belongs here:** Provider classes (`OpenAIVideoProvider`, `VertexAIProvider`, `GeminiVeoProvider`, etc.), `BaseProvider` and its subclasses, request/response transformation functions (`transformRequestBody`, `transformResponse`), stream handling (`handleStream`, `duplicateStream`, `supportsStream`), URL signing (`generateSignedUrl`, `parseGcsUri`), and provider type identification (`getType`, `isVideoContentDownload`). +- **Does NOT belong here:** High-level API routing, external request orchestration, or storage management (handled by other clusters/services). Data models like `Transaction`, `LlmTransactionMetadata`, or `SupportedVideoModel` are referenced but managed elsewhere. UI or client-facing logic is outside scope. + +## Invariants +- `getType()` must reliably return the correct `ProviderType` for each provider subclass; this is critical for downstream routing. +- `supportsStream()` must accurately reflect whether the provider supports streaming; inconsistent states can cause runtime errors. +- `duplicateStream()` must produce two independent streams without data loss or corruption; failure here breaks streaming guarantees. +- `transformRequestBody()` and `transformResponse()` must preserve data integrity, handle errors gracefully, and conform to expected formats. +- `generateSignedUrl()` must produce valid, unexpired URLs; invalid URLs lead to failed resource access. +- `parseGcsUri()` must correctly parse GCS URIs; malformed URIs should throw or handle errors explicitly. +- `handleStream()` must manage backpressure, errors, and resource cleanup; leaks or unhandled errors cause instability. +- `isVideoContentDownload()` must be accurate; misclassification affects downstream processing. +- `getApiKey()` can return `undefined`, but if provided, must be valid and authorized. +- `duplicateStream()` must not mutate original streams or cause side effects. +- Provider classes extending `BaseProvider` must implement all abstract methods; missing implementations lead to runtime errors. + +## Patterns +- Use `getType()` as a discriminator for provider routing. +- Always check `supportsStream()` before invoking streaming methods; fallback to non-streaming logic if unsupported. +- When handling streams, use `duplicateStream()` to enable multiple consumers without data loss. +- Wrap external API calls with `try/catch`; propagate errors as `HttpError` or custom errors. +- Use `formatUpstreamUrl()` to construct provider-specific URLs, ensuring consistent upstream communication. +- Use `transformRequestBody()` and `transformResponse()` to normalize data formats; maintain idempotency. +- For signed URLs, parse URIs with `parseGcsUri()` before signing with `generateSignedUrl()`. +- When modifying request headers, use `formatAuthHeaders()` to inject authentication reliably. +- Follow naming conventions: methods like `getType()`, `isVideoContentDownload()`, `supportsStream()` are standard; avoid inconsistent naming. +- Use `handleBody()` for processing incoming request bodies, ensuring transaction consistency. +- When dealing with streaming responses, always invoke `handleStream()` with proper error handling. + +## Pitfalls +- **Frequent modifications:** Methods like `getType()`, `isVideoContentDownload()`, and `duplicateStream()` are hot spots; avoid breaking existing contracts. +- **High coupling:** Changes in `BaseProvider` or its subclasses may ripple; ensure backward compatibility. +- **Stream handling errors:** Failing to properly duplicate or manage streams can cause data loss, leaks, or crashes. +- **Incorrect URL signing:** Misparsing URIs or using invalid credentials leads to inaccessible resources. +- **Inconsistent provider types:** Returning wrong `ProviderType` from `getType()` causes routing errors. +- **Churn in provider classes:** Frequent updates to provider subclasses (`OpenAIVideoProvider`, `GeminiVeoProvider`, etc.) require careful version control. +- **Null safety:** `getApiKey()` may return `undefined`; callers must handle absence gracefully. +- **Error propagation:** `handleStream()` and `processStreamData()` must handle all errors internally; unhandled exceptions cause instability. +- **Unsupported features:** Calling `supportsStream()` on providers that do not support streaming leads to runtime failures. +- **Resource leaks:** Not cleaning up streams or failing to handle backpressure in `handleStream()` can cause memory issues. + +## Dependencies +- **External:** + - `Decimal` for precise cost calculations. + - `TextDecoder` for decoding streamed data. + - `pipeline` for stream piping and error handling. + - `responses`, `route`, `tokens`, `transformations`, `video`, `videos` for various utilities. +- **Internal:** + - `HttpError` for error handling. + - `formatUpstreamUrl()` for URL construction. + - Provider classes (`GeminiGPTProvider`, `GPTProvider`, `AnthropicGPTProvider`, `OpenAIBaseProvider`, etc.) as base or related providers. + - Data models (`Transaction`, `LlmTransactionMetadata`, `SupportedVideoModel`, etc.). + - Services like `EchoControlService`, `HandleNonStreamingService`. + - Storage utilities (`Storage`, `parseGcsUri()`, `generateSignedUrl()`). +- **Usage notes:** Always verify provider-specific behaviors (e.g., streaming support, URL signing) via their methods before invocation. Use `getType()` to route requests correctly. Maintain consistency in request/response transformations to avoid data corruption or protocol mismatches. + +--- + +**Summary:** +Agents working with this cluster must understand provider-specific contracts, especially around streaming support, URL signing, and request transformation. They must respect the invariants to prevent runtime failures, follow established patterns for data handling, and be vigilant about the frequent churn in core methods. Proper dependency management and error handling are critical to maintain stability and correctness. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_4f19bbcc.md b/packages/app/server/src/AGENTS_this_cluster_manages_4f19bbcc.md new file mode 100644 index 000000000..b1f4a758b --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_4f19bbcc.md @@ -0,0 +1,53 @@ +# Video Generation Handling and Transaction Management + +## Purpose +This cluster manages post-video-generation workflows, including handling successful video creation events, parsing responses from external operations, and creating financial transactions related to generated videos. It encapsulates logic for coordinating external services, transaction integrity, and response validation. + +## Boundaries +- **Belongs here:** + - Handling successful video generation events (`handleSuccessfulVideoGeneration`) + - Parsing responses from external operation endpoints (`parseCompletedOperationsResponse`) + - Creating and managing transactions (`createTransaction`) + - Accessing service account credentials (`getServiceAccountCredentials`) for authentication purposes + +- **Does NOT belong here:** + - Actual video processing or encoding logic (handled elsewhere) + - External API request implementations (only response parsing and credential retrieval) + - User interface or client-facing components + - Business logic unrelated to video generation or transaction creation (e.g., user management, analytics) + +## Invariants +- `handleSuccessfulVideoGeneration` must only execute after a video is confirmed successfully generated; it should not process invalid or incomplete video IDs. +- `parseCompletedOperationsResponse` must return `true` only if the response data indicates a completed and valid operation; it must handle unexpected or malformed data gracefully, avoiding exceptions. +- `createTransaction` must ensure the `transaction` object is valid, complete, and consistent with the current state; it should not create duplicate or conflicting transactions. +- `getServiceAccountCredentials` must always return valid credentials; if credentials are invalid or missing, subsequent operations depending on them must fail safely. +- All methods should respect asynchronous patterns, avoiding race conditions especially around transaction creation and response parsing. + +## Patterns +- Use explicit null/undefined checks when handling response data in `parseCompletedOperationsResponse`. +- Follow consistent naming conventions: methods prefixed with `handle`, `get`, `parse`, `create`. +- When modifying `handleSuccessfulVideoGeneration`, ensure idempotency if invoked multiple times for the same `videoId`. +- Error handling should be explicit; catch exceptions in async methods and log or propagate as appropriate. +- Credential retrieval via `getServiceAccountCredentials` should cache credentials if possible, to avoid repeated expensive calls. +- When creating transactions, validate the `transaction` object structure against the `Transaction` interface before proceeding. + +## Pitfalls +- Frequently modified methods (`handleSuccessfulVideoGeneration`, `getServiceAccountCredentials`, `parseCompletedOperationsResponse`, `createTransaction`) are prone to introducing bugs; ensure thorough testing after each change. +- Relying on response data without proper validation can lead to false positives/negatives in `parseCompletedOperationsResponse`. +- Ignoring race conditions or asynchronous side effects in `createTransaction` can cause duplicate or inconsistent transactions. +- Hardcoded assumptions about credentials or response formats may break if external APIs change; always validate externally fetched data. +- Churn in these methods suggests they are core to critical workflows; avoid untested refactors that could disrupt video or transaction workflows. + +## Dependencies +- **External Imports:** + - `queryRawUnsafe`: Use cautiously; ensure sanitization to prevent injection or security issues when executing raw queries. + - `transaction`: Leverage this for transaction creation; validate its structure and lifecycle management. + +- **References:** + - `Transaction`: Must be validated before creation; ensure all required fields are populated. + - `GeneratedVideo`: Use as a reference for video IDs and status checks; ensure consistency between video state and transaction logic. + +- **Usage Tips:** + - Always retrieve service account credentials via `getServiceAccountCredentials` before performing operations requiring authentication. + - When parsing responses, handle all possible data shapes; do not assume success unless explicitly validated. + - Maintain idempotency in `handleSuccessfulVideoGeneration` to prevent duplicate processing. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_5d1a3d4d.md b/packages/app/server/src/AGENTS_this_cluster_manages_5d1a3d4d.md new file mode 100644 index 000000000..3ed3f29cb --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_5d1a3d4d.md @@ -0,0 +1,57 @@ +# Semantic Cluster: HTTP Request Handling & Access Control (packages/app/server/src) + +## Purpose +This cluster manages outbound HTTP requests to upstream services, constructs base URLs dynamically, and verifies user access permissions. It encapsulates core logic for external communication and access validation, ensuring secure and flexible integrations. + +## Boundaries +- **Belongs here:** + - `makeUpstreamRequest`: Handles all outbound fetch requests, including headers, method, and body management. + - `getBaseUrl`: Resolves environment-dependent URLs, possibly influenced by request paths. + - `confirmAccessControl`: Validates user permissions against provider IDs, relying on external or internal access policies. +- **Does NOT belong here:** + - Internal business logic unrelated to HTTP communication or access control (e.g., data processing, domain logic). + - Authentication token management or session handling—these should be handled upstream or in dedicated auth modules. + - External dependencies like `Transaction` are referenced but not directly used; transaction management should be handled outside this cluster. + +## Invariants +- `makeUpstreamRequest`: + - Always returns a `Response` object; do not resolve or handle errors internally—let callers manage exceptions. + - Headers must be explicitly provided; defaults are not assumed. + - Body parameter can be `string`, `FormData`, or `undefined`; handle each appropriately. +- `getBaseUrl`: + - Must return a valid URL string; fallback to environment variables if `reqPath` is undefined. + - Should be deterministic and cacheable if needed, but avoid side effects. +- `confirmAccessControl`: + - Returns `true` only if access is explicitly granted; false otherwise. + - User ID and provider ID are mandatory; null or undefined values are invalid inputs. + - Should not perform side effects; only validation logic. + +## Patterns +- Use consistent naming: `makeUpstreamRequest`, `getBaseUrl`, `confirmAccessControl`. +- Error handling: propagate exceptions; do not swallow errors silently. +- URL construction: prefer environment variables or configuration for base URL; append `reqPath` carefully. +- Access control: ensure `userId` and `providerId` are validated before processing. +- Frequently modify functions (`makeUpstreamRequest`, `getBaseUrl`, `confirmAccessControl`) suggest high churn; review version history for stability concerns. + +## Pitfalls +- Churn-prone functions: frequent modifications increase risk of regressions or inconsistent behavior. +- `makeUpstreamRequest`: neglecting to set headers or handling body types correctly leads to request failures. +- `getBaseUrl`: incorrect URL resolution may cause downstream failures; caching without invalidation can cause stale URLs. +- `confirmAccessControl`: assuming permissions are static; should re-validate if permissions change dynamically. +- Null or undefined inputs for `userId`, `providerId`, or `reqPath` can cause runtime errors if not validated. +- External dependencies like `Transaction` are referenced but not used; improper transaction handling may lead to inconsistent states. + +## Dependencies +- **References to Transaction:** + - The cluster depends on transaction context for certain operations; ensure transaction boundaries are respected outside these methods. + - Use transaction-aware patterns when extending access control or request logic. +- **External imports:** None explicitly; rely on standard APIs (`fetch`, environment variables). +- **Configuration:** + - Base URL resolution depends on environment variables or configuration files; ensure these are correctly set and validated at startup. +- **Access control logic:** + - Should integrate with existing user and provider permission systems; avoid hardcoded rules. + +--- + +**Summary:** +Agents modifying this cluster must prioritize error propagation, respect the high churn nature of core functions, and ensure URL and permission validation are robust. Be cautious of frequent updates; validate assumptions about environment and state. Maintain strict separation of concerns—HTTP request logic, URL resolution, and access validation should remain decoupled. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_5e4c050e.md b/packages/app/server/src/AGENTS_this_cluster_manages_5e4c050e.md new file mode 100644 index 000000000..2957139b0 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_5e4c050e.md @@ -0,0 +1,47 @@ +# Semantic Cluster: Server-side Markup and URI Transformation + +## Purpose +This cluster manages retrieval of current markup data associated with a specific Echo App ID and transforms response URIs within response data objects, ensuring correct URI resolution and data consistency for server-side rendering or processing. + +## Boundaries +- **Belongs here:** + - Fetching markup data tied to an Echo App ID (`getCurrentMarkupByEchoAppId`) + - Modifying response data objects to update or normalize URIs (`transformResponseUris`) +- **Does NOT belong here:** + - Data persistence or database interactions (should be handled by data access layers) + - Client-side rendering logic or UI-specific code + - External API calls outside the scope of response URI transformation or markup retrieval + - Authentication, authorization, or session management + +## Invariants +- `getCurrentMarkupByEchoAppId` must always return the latest markup associated with the provided `echoAppId`; caching or stale data invalidation is outside this method’s scope. +- `transformResponseUris` must mutate the input `responseData` in-place, updating all URIs consistently; it should not replace the entire object. +- URIs within `responseData` should be normalized to a canonical form, avoiding duplicates or malformed URLs. +- Null or undefined values in `responseData` should be safely ignored; no exceptions should be thrown due to missing or malformed URI fields. +- The methods are asynchronous; callers must await their completion before proceeding with dependent logic. + +## Patterns +- Use explicit null/undefined checks before URI transformation to prevent runtime errors. +- Follow consistent naming conventions: `getCurrentMarkupByEchoAppId`, `transformResponseUris`. +- When transforming URIs, prefer immutable updates where possible; mutate only the necessary fields. +- Handle errors gracefully; log failures but do not let exceptions propagate unless critical. +- Document assumptions about the structure of `responseData`, especially URI locations and formats. +- For `getCurrentMarkupByEchoAppId`, cache results if multiple calls with the same `echoAppId` are expected, unless invalidated; this is optional but recommended for performance. + +## Pitfalls +- Frequent modifications to both methods increase risk of introducing bugs; ensure thorough testing, especially for edge cases like missing or malformed URIs. +- Null-safety is critical; failure to check for undefined or null fields can cause runtime errors. +- Be cautious of race conditions if `getCurrentMarkupByEchoAppId` is called concurrently; consider caching or synchronization if needed. +- When transforming URIs, avoid overwriting unrelated fields; limit scope strictly to URI-related data. +- Avoid assumptions about URI format; validate URLs before transformation. +- Since these methods are frequently modified, document changes meticulously to prevent regressions. + +## Dependencies +- No explicit external dependencies are declared. +- When implementing URI transformations, utilize standard URL parsing libraries or APIs to ensure correctness. +- For logging or error handling, integrate with existing application logging frameworks, respecting their conventions. +- If caching is introduced in `getCurrentMarkupByEchoAppId`, ensure thread-safe mechanisms are used to prevent stale data or race conditions. + +--- + +**Note:** This cluster’s methods are core to server-side markup and URI management; understanding their invariants, patterns, and pitfalls ensures reliable, maintainable code. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_5f9b7076.md b/packages/app/server/src/AGENTS_this_cluster_manages_5f9b7076.md new file mode 100644 index 000000000..67e9528e5 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_5f9b7076.md @@ -0,0 +1,50 @@ +# Semantic Cluster: Transaction and Provider Management (packages/app/server/src) + +## Purpose +This cluster manages provider configurations, transaction creation, and access control for different AI service providers, encapsulating provider metadata, transaction lifecycle, and tier-based billing logic. It ensures consistent handling of provider URLs, API keys, and transaction metadata across the system. + +## Boundaries +- **Belongs here:** Provider metadata accessors (`getBaseUrl`, `getType`, `getApiKey`, `getIsStream`), transaction creation methods (`createTransactionRecord`, `createFreeTierTransaction`, `createPaidTransaction`, `createX402Transaction`), access control (`confirmAccessControl`), tier spend pool retrieval (`getOrNoneFreeTierSpendPool`), and transaction metadata type guards (`isLlmTransactionMetadata`, `isVeoTransactionMetadata`). +- **Does NOT belong here:** UI logic, user authentication, or billing system integrations outside of transaction creation. Provider registration/configuration outside of this module should be elsewhere. External API calls or network logic are outside scope unless invoked within these methods. + +## Invariants +- `getBaseUrl()` must always return a valid URL string; multiple overloads should be consistent. +- `getType()` returns a fixed `ProviderType` enum; it must not change during runtime. +- `getApiKey()` may return `undefined`; code must handle absence gracefully. +- `confirmAccessControl()` must reliably verify user-provider relationships; always return `false` on errors. +- Transaction creation methods (`createTransactionRecord`, `createFreeTierTransaction`, `createPaidTransaction`, `createX402Transaction`) must produce valid `Transaction` objects or `null` if creation fails. +- `createFreeTierTransaction()` must associate with a valid `spendPoolId`. +- Metadata type guards (`isLlmTransactionMetadata`, `isVeoTransactionMetadata`) must be mutually exclusive and correctly identify metadata types. +- All methods interacting with `transaction` dependency must handle async errors explicitly. +- `getIsStream()` indicates streaming capability; its value is critical for downstream flow control. + +## Patterns +- Use consistent method naming: `getBaseUrl`, `getType`, `getApiKey`, `confirmAccessControl`. +- Overloaded `getBaseUrl()` should always return the same URL for a given instance; avoid inconsistent overrides. +- Transaction creation methods should validate input data before proceeding. +- Use `Promise`-based async methods with explicit error handling. +- Type guards (`isLlmTransactionMetadata`, `isVeoTransactionMetadata`) should be used to narrow metadata types safely. +- Default parameters (e.g., `addEchoProfit: boolean = true`) should be explicitly set to avoid ambiguity. +- Maintain clear separation between provider metadata access and transaction logic. + +## Pitfalls +- Multiple `getBaseUrl()` overloads increase risk of inconsistent URL returns; ensure all are synchronized. +- Frequent modifications to `getBaseUrl()` (noted by high churn) suggest potential instability; avoid introducing side effects. +- Relying on `getApiKey()` being `undefined` requires null-safe handling everywhere. +- Misuse of type guards can lead to incorrect metadata processing; verify mutually exclusiveness. +- Transaction creation functions depend on external `transaction` dependency; mishandling async errors can cause silent failures. +- Tier spend pool retrieval (`getOrNoneFreeTierSpendPool`) may return `undefined`; callers must handle this case. +- Frequent churn in URL and stream indicator methods indicates potential for bugs if not carefully maintained. +- Avoid side effects in accessor methods; they should be pure and predictable. + +## Dependencies +- **External:** `transaction` module for transaction handling. +- **References:** `LlmTransactionMetadata`, `VeoTransactionMetadata`, `Transaction` interfaces. +- **Usage:** Ensure `createPaidTransaction` and `createFreeTierTransaction` are invoked with valid data; handle `null` returns. +- **Correctness:** Use `isLlmTransactionMetadata` and `isVeoTransactionMetadata` guards before processing metadata to prevent runtime errors. +- **Resource Management:** Transaction methods should manage database connections or transaction contexts explicitly if extended beyond current scope. +- **Integration:** Confirm that `confirmAccessControl()` correctly interfaces with user-provider relationship data sources; avoid assumptions about data consistency. + +--- + +**Note:** AI agents should prioritize understanding the invariants and patterns to prevent breaking contracts, especially around URL consistency, transaction validity, and metadata type safety. Pay close attention to the high churn areas (`getBaseUrl`, `getIsStream`) to avoid introducing bugs during modifications. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_686b81d2.md b/packages/app/server/src/AGENTS_this_cluster_manages_686b81d2.md new file mode 100644 index 000000000..94268ce00 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_686b81d2.md @@ -0,0 +1,51 @@ +# Semantic Cluster: OpenAI Schema and Request Data Service + +## Purpose +This cluster manages schema definitions for OpenAI integrations related to video and image processing, and provides a service (`RequestDataService`) to handle request data preparation and dispatch. It encapsulates the data contracts and request orchestration for AI API calls within the server. + +## Boundaries +- **Belongs here:** + - Schema definitions for OpenAI video (`openai.ts`) and image (`openai.ts`) modules, including data types, interfaces, and validation logic. + - Request data handling logic within `RequestDataService.ts`, including request construction, parameter validation, and request dispatching. +- **Does NOT belong here:** + - Actual API call implementation (handled via `request` dependency elsewhere). + - Business logic unrelated to data schemas or request orchestration (e.g., user management, storage, or UI concerns). + - External API response processing beyond the scope of request data preparation. + +## Invariants +- Schema modules (`video/openai.ts`, `image/openai.ts`) must strictly define data contracts, including required fields, types, and validation rules; no optional or loosely typed fields. +- `RequestDataService` must always invoke `request` with properly validated, well-formed request objects conforming to schema definitions. +- Request payloads must not include sensitive data unless explicitly permitted; enforce data sanitization before dispatch. +- The sequence of request preparation steps (validation → serialization → dispatch) must be strictly followed; no skipping validation. +- Null values are disallowed unless explicitly specified as nullable in the schema; avoid undefined or missing fields in request payloads. +- Frequently modified files (`video/openai.ts`, `image/openai.ts`, `RequestDataService.ts`) indicate active evolution—agents should verify compatibility after updates. + +## Patterns +- Use consistent naming conventions for schema properties, preferring camelCase. +- Validate all input data against schema types before request dispatch. +- Encapsulate request construction logic within `RequestDataService`, avoiding duplication. +- Handle errors explicitly: catch validation failures and request errors; log or propagate as needed. +- When modifying schemas, ensure backward compatibility if schemas are used across multiple request types. +- Follow existing request calling pattern: prepare data → call `request` with method, URL, headers, body. +- Use constants or enums for API endpoints and request types to prevent typos. +- Document schema fields with comments for clarity, especially for optional or nullable fields. + +## Pitfalls +- **Schema drift:** Inconsistent or incomplete schema definitions can cause runtime errors or invalid requests. +- **Churn hazards:** Frequent modifications in `video/openai.ts`, `image/openai.ts`, and `RequestDataService.ts` increase risk of breaking request contracts; always verify request payloads post-change. +- **Null-safety violations:** Missing null checks or optional fields may lead to runtime exceptions. +- **Request misformation:** Failing to validate data before calling `request` can result in malformed API calls. +- **Coupling with request:** Over-reliance on `request` without proper validation or error handling can cause silent failures. +- **Schema versioning:** No explicit versioning in schemas; consider version fields if API evolves. +- **Concurrency issues:** No explicit concurrency control; ensure request data is prepared atomically if used in concurrent contexts. + +## Dependencies +- **`request` function:** Use strictly for outbound API calls; ensure request parameters are validated and correctly formatted. +- **Response handling:** External `response` import indicates response processing occurs outside this cluster; ensure responses are parsed and errors handled appropriately outside these schemas/services. +- **Type safety:** Leverage TypeScript types from schema modules to enforce data integrity during request construction. +- **Validation libraries (if used):** Use consistent validation methods across schemas to prevent discrepancies. +- **Logging/Monitoring:** Implement logging around request dispatch and error handling to facilitate debugging, especially given high churn in related files. + +--- + +**Note:** Agents should monitor schema files (`openai.ts`) for frequent updates, verify request data validity after modifications, and ensure strict adherence to invariants and patterns to maintain request integrity. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_6cf9837a.md b/packages/app/server/src/AGENTS_this_cluster_manages_6cf9837a.md new file mode 100644 index 000000000..e95d4149d --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_6cf9837a.md @@ -0,0 +1,42 @@ +# User Context and Utility Functions + +## Purpose +This cluster manages user identification and model version checks within the server, providing core methods (`getUser`, `getUserId`, `isVeo3Model`) that underpin user-specific logic and feature toggles. It encapsulates logic for retrieving user data and determining model compatibility. + +## Boundaries +- **Belongs here:** User data retrieval (`getUser`, `getUserId`), model version checks (`isVeo3Model`), and related utility functions in `utils.ts`. +- **Does NOT belong here:** Authentication flows, session management, or external API calls unrelated to user or model info. Those should be handled in dedicated auth or API modules. + +## Invariants +- `getUser()` must return `null` if no user is authenticated; never throw exceptions. +- `getUserId()` must return a consistent string identifier or `null`; should not return empty strings. +- `isVeo3Model()` must reliably reflect the current model version; should cache results if performance is critical but invalidate on relevant updates. +- User data dependencies (e.g., from context or session) should be synchronized with the actual user state. +- Utility functions in `utils.ts` are frequently modified; avoid introducing side effects that could break invariants. + +## Patterns +- Use explicit null checks; do not assume presence of user data. +- Follow naming conventions: `getUser`, `getUserId`, `isVeo3Model`. +- When modifying, preserve idempotency: `getUser()` should consistently return the same user object unless user state changes. +- Handle errors gracefully; avoid unhandled exceptions. +- Cache results of `isVeo3Model()` if performance is critical, but ensure cache invalidation aligns with model updates. +- Use dependency injection for external dependencies like `CdpClient` when extending functionality. + +## Pitfalls +- Frequently modified functions (`getUser`, `getUserId`, `isVeo3Model`) are prone to regressions; ensure thorough testing. +- Null-safety: forget to handle `null` cases in consumer code leads to runtime errors. +- Assumptions about user presence can cause bugs; always check for `null`. +- Caching `isVeo3Model()` without proper invalidation can cause stale data. +- External dependencies (`amount`, `prefix`) are imported but not used here; ensure they are relevant or remove to avoid confusion. +- Avoid tight coupling with external user management; rely on the provided methods. + +## Dependencies +- **User** entity: must be correctly structured and available in context. +- **CdpClient**: external API client; use carefully, especially regarding asynchronous calls or side effects. +- **amount**, **prefix**: utility functions or constants; ensure their usage aligns with current code patterns. +- **utils.ts**: contains auxiliary functions; modifications should preserve existing invariants and patterns. + +--- + +**Summary:** +This cluster provides foundational user and model version info critical for feature gating and user-specific logic. AI agents must understand the null-safety contracts, caching considerations, and the scope of data dependencies. Careful handling of modifications, especially around frequently changing methods, is essential to maintain stability. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_75fed782.md b/packages/app/server/src/AGENTS_this_cluster_manages_75fed782.md new file mode 100644 index 000000000..5daeb2bb6 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_75fed782.md @@ -0,0 +1,41 @@ +# Semantic Cluster: Error Handling & Markup Validation (packages/app/server/src) + +## Purpose +This cluster manages upstream error handling via `handleUpstreamError` and validates markup data with `validateMarkup`. It ensures robust error propagation and data integrity within server request flows. + +## Boundaries +- **Belongs here:** Error handling for upstream responses (`handleUpstreamError`), markup data validation (`validateMarkup`). +- **Does NOT belong:** Core network request logic, response serialization, or UI rendering; these are outside this cluster’s scope. ValidationResult and Decimal are dependencies but not part of core business logic. + +## Invariants +- `handleUpstreamError` must **never** swallow errors silently; it should propagate or transform errors appropriately. +- `response` parameter in `handleUpstreamError` must be a valid `globalThis.Response` object; null or undefined responses are invalid. +- `validateMarkup` must **not** mutate `markUp`; it should only read and validate. +- `ValidationResult` must accurately reflect the validity state; invalid results should include specific error details. +- All error handling should preserve original error context for debugging. +- `validateMarkup` must handle all expected data fields, returning a comprehensive `ValidationResult`. + +## Patterns +- Use consistent naming: `handleUpstreamError`, `validateMarkup`. +- Error handling pattern: catch, log, transform, or rethrow errors; avoid silent failures. +- Validation pattern: return detailed `ValidationResult` objects; avoid throwing exceptions for validation failures. +- Churn-sensitive: frequently modified; ensure backward compatibility when updating logic. +- Asynchronous handling: `handleUpstreamError` is async; always await promises. +- Use `Decimal` for numeric precision where applicable, especially in validation or calculations. + +## Pitfalls +- **Silent failures:** Failing to propagate errors in `handleUpstreamError` can cause downstream issues. +- **Null/undefined assumptions:** Not validating `response` or `markUp` inputs can lead to runtime errors. +- **Churn risk:** Frequent modifications increase risk of introducing bugs; document assumptions thoroughly. +- **Validation gaps:** Incomplete validation logic in `validateMarkup` may allow invalid data. +- **Error context loss:** Not preserving original error info in `handleUpstreamError` hampers debugging. +- **Dependency misuse:** Incorrect usage of `Decimal` or `ValidationResult` can cause subtle bugs. + +## Dependencies +- **ValidationResult:** Must be used to convey validation status; ensure it’s correctly constructed and interpreted. +- **Decimal:** Use for precise numeric operations; avoid floating-point errors in validation or calculations. +- **External imports:** Be cautious of version mismatches; ensure `Decimal` is correctly imported and used consistently. + +--- + +**Note:** Given the high churn rate, agents should pay special attention to recent changes in `handleUpstreamError` and `validateMarkup`, verifying that error handling and validation logic remain robust and backward compatible. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_7d3fa1e4.md b/packages/app/server/src/AGENTS_this_cluster_manages_7d3fa1e4.md new file mode 100644 index 000000000..daf12faba --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_7d3fa1e4.md @@ -0,0 +1,54 @@ +# Semantic Cluster: Tavily Transaction Creation & Resource Types + +## Purpose +This cluster manages the creation of Tavily transactions via the `createTavilyTransaction` function, which transforms search inputs and outputs into a standardized Transaction object, relying on specific resource types and provider modules. It encapsulates the logic for translating search data into transactional records within the server context. + +## Boundaries +- **Belongs here:** + - `createTavilyTransaction` function logic, including input validation, cost handling, and output transformation. + - Resource type definitions in `types.ts` that define the shape of Tavily search inputs and outputs. + - Route handling code in `route.ts` that invokes transaction creation. + - Provider integrations in `XAIProvider.ts` that supply auxiliary data or context. +- **Does NOT belong here:** + - Core transaction management unrelated to Tavily-specific data. + - External API calls outside the scope of `createTavilyTransaction`. + - Business logic unrelated to search input/output transformation. + - UI rendering or client-facing components. + +## Invariants +- `createTavilyTransaction` must always produce a valid `Transaction` object conforming to the expected schema. +- The `cost` parameter must be a non-negative `Decimal`; negative costs are invalid. +- The `TavilySearchInput` and `TavilySearchOutput` must be validated before invocation; the function assumes they are well-formed. +- The resource types in `types.ts` must remain consistent; any change requires updating dependent logic. +- The `Transaction` reference used for dependency must be kept up-to-date; it is central to transaction processing. +- The function should not mutate its input parameters. +- The route handling in `route.ts` should not invoke `createTavilyTransaction` with malformed or incomplete data. + +## Patterns +- Use explicit type annotations for all parameters and return types. +- Validate `cost` to prevent negative values before creating the `Transaction`. +- Maintain consistent naming conventions: `createTavilyTransaction`, `TavilySearchInput`, `TavilySearchOutput`. +- Handle errors gracefully; if input validation fails, throw specific exceptions or return error objects. +- Use dependency injection or import statements explicitly for `Transaction` and resource types. +- Log key steps during transaction creation for traceability, especially in hot-churn modules. +- When modifying `route.ts`, ensure route parameters are sanitized and validated before calling `createTavilyTransaction`. + +## Pitfalls +- **Churn Hotspots:** Frequent modifications in `route.ts`, `createTavilyTransaction`, and resource types increase risk of breaking invariants or introducing bugs. +- **Null Safety:** Failing to validate inputs may lead to null reference errors; always validate `TavilySearchInput` and `TavilySearchOutput`. +- **Cost Handling:** Neglecting to enforce non-negative `cost` can produce invalid transactions. +- **Type Mismatches:** Changes in resource type definitions (`types.ts`) can cause runtime errors if not synchronized. +- **Dependency Updates:** Upgrading `Transaction` or resource modules without testing can break downstream logic. +- **Concurrency:** No explicit mention of concurrency control; ensure transaction creation is thread-safe if invoked concurrently. +- **Frequent Churn:** High modification frequency suggests the need for robust testing and version control to prevent regressions. + +## Dependencies +- **Transaction:** Must be referenced accurately; any updates to the `Transaction` schema require corresponding updates in `createTavilyTransaction`. +- **Resource Types (`types.ts`):** Ensure resource type definitions for `TavilySearchInput` and `TavilySearchOutput` are consistent and validated. +- **XAIProvider.ts:** Use this provider for auxiliary data; understand its API and ensure correct data retrieval. +- **Route Module:** Coordinate with `route.ts` to ensure correct invocation and parameter passing. +- **External Libraries:** No external imports are indicated; rely on internal modules and standard libraries for validation and data handling. + +--- + +**Note:** Always review high-churn modules for recent changes before modifying logic to prevent regressions. Maintain strict validation and error handling to uphold invariants. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_80b16f4b.md b/packages/app/server/src/AGENTS_this_cluster_manages_80b16f4b.md new file mode 100644 index 000000000..2ec4b346b --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_80b16f4b.md @@ -0,0 +1,58 @@ +# Semantic Cluster: Payment and Resource Settlement Handlers (packages/app/server/src) + +## Purpose +This cluster manages payment validation, resource settlement, and communication with clients via streams. It encapsulates core logic for handling payment verification, refunds, resource finalization, and response generation, ensuring secure, consistent transaction flows and protocol compliance. + +## Boundaries +- **Belongs here:** Payment validation (`getApiKey`, `validateXPaymentHeader`), settlement (`settle`, `finalize`), refunds (`refund`), resource finalization (`finalizeResource`), response building (`buildX402Response`, `buildX402Challenge`), and stream output (`streamToClient`). +- **Does NOT belong here:** Low-level network transport, unrelated API endpoints, UI rendering, or unrelated business logic (e.g., user management). Modules like `resources/handler.ts` and `handlers/settle.ts` are part of this cluster; unrelated modules should be refactored out. + +## Invariants +- `getApiKey()` must return a consistent, valid API key or undefined if absent; never null. +- `validateXPaymentHeader()` must strictly verify header integrity; invalid headers throw or reject. +- `settle()` and `finalize()` must only process valid, verified `SettleRequest` and `ExactEvmPayload` objects. +- Refunds and finalizations must respect the `originalPaymentAmountDecimal` and `transaction` state; never process mismatched or incomplete data. +- `streamToClient()` must handle `NodeWebReadableStream` without resource leaks; always close streams properly. +- Responses built via `buildX402Response()` and `buildX402Challenge()` must conform to protocol specs; no malformed responses. +- Churn in functions like `streamToClient`, `getApiKey`, and `handleFailedVideoGeneration` indicates frequent updates; avoid breaking existing contracts during modifications. +- External dependencies (`BigInt`, `Decimal`, `transaction`) are assumed reliable; validate their inputs before use. + +## Patterns +- Use `async/await` for all I/O-bound operations; handle errors explicitly. +- Validate headers and payloads early; reject invalid data immediately. +- Generate nonces with `generateRandomNonce()` to prevent replay attacks. +- Convert between `Decimal` and `bigint` using `decimalToUsdcBigInt()` and `usdcBigIntToDecimal()`; maintain precision. +- Use `buildX402Challenge()` to create challenge strings; ensure parameters are correctly formatted. +- Refunds and finalizations should be atomic; ensure state consistency. +- Stream responses with `streamToClient()`; handle backpressure and stream errors gracefully. +- Maintain strict separation between payment validation (`getApiKey`, `validateXPaymentHeader`) and resource handling (`finalizeResource`, `settle`). + +## Pitfalls +- Frequent modifications to `streamToClient`, `getApiKey`, and `handleFailedVideoGeneration` increase risk of introducing bugs; test thoroughly after changes. +- Misuse of `Decimal` conversions can cause precision errors; always validate conversions. +- Improper header validation may lead to security vulnerabilities; enforce strict checks. +- Inconsistent state management in `settle`, `finalize`, and `refund` can cause double refunds or resource leaks. +- Relying on external modules like `transaction` and `BigInt` without validation may cause runtime errors. +- Churn hotspots suggest these functions are fragile; avoid refactoring without comprehensive tests. +- Protocol compliance in `buildX402Response` and `buildX402Challenge` is critical; malformed responses break client interactions. +- Handling of `originalPaymentAmountDecimal` and `transaction` must be synchronized; mismatches lead to incorrect refunds or finalizations. + +## Dependencies +- **Internal:** + - `getSmartAccount()`: Use to retrieve the current smart account; ensure it’s valid before proceeding. + - `transfer()`: Call only after thorough validation; handle transfer errors explicitly. + - `Url`, `Transaction`: Use for transaction referencing; validate their states before use. +- **External:** + - `BigInt`, `Decimal`: Use for precise numeric calculations; validate inputs and outputs. + - `Note`, `cost`, `esc`, `executeResource`, `queryRawUnsafe`: Use for logging, cost calculations, resource execution, and raw queries; ensure correct usage patterns. + - `transaction`: Use for transaction management; handle failures gracefully. +- **Protocol & Security:** + - Ensure headers and payloads conform to expected formats (`VerifyRequest`, `PaymentPayload`, `ExactEvmPayload`). + - Validate API keys and headers before processing sensitive operations. + - Use `generateRandomNonce()` for challenge-response mechanisms to prevent replay attacks. +- **Interaction with External Services:** + - Coordinate with `facilitatorProxy`, `server.ts`, and request handlers (`handleX402Request`, `handleApiKeyRequest`, `handleResourceRequest`) to maintain protocol integrity and security. + +--- + +This dense, actionable knowledge ensures AI agents understand the deep, non-obvious constraints, patterns, and dependencies critical for effective, safe modifications within this code cluster. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_9bda1dbd.md b/packages/app/server/src/AGENTS_this_cluster_manages_9bda1dbd.md new file mode 100644 index 000000000..aff006f6f --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_9bda1dbd.md @@ -0,0 +1,52 @@ +# GPT Client and OpenRouterProvider Integration + +## Purpose +This cluster manages the interaction with OpenAI's API via the `gpt-client.ts` module, primarily through the `makeRequest` function, and the configuration/provider setup in `OpenRouterProvider.ts`. It encapsulates request handling, streaming options, and provider configuration necessary for AI-powered features. + +## Boundaries +- **Belongs here:** + - All logic related to constructing, sending, and receiving GPT API requests within `makeRequest`. + - Provider setup, including API keys, endpoints, and configuration in `OpenRouterProvider.ts`. +- **Does NOT belong here:** + - Business logic unrelated to GPT API interactions (e.g., user management, UI). + - Data persistence or caching mechanisms outside the scope of request handling. + - External API integrations other than OpenAI. + +## Invariants +- `makeRequest` must always handle `useStreaming` boolean explicitly; default is `false`. +- API requests must include proper authentication headers; missing or invalid keys should trigger errors. +- Streaming responses, if enabled, must be processed incrementally without losing data integrity. +- `OpenRouterProvider` must supply a valid configuration object before any request is made. +- No request should proceed if the provider configuration is invalid or incomplete. +- All API responses should be validated for expected structure; malformed responses must trigger error handling. +- Resource cleanup (e.g., abort controllers) must be handled to prevent leaks during streaming or retries. + +## Patterns +- Use consistent naming: `makeRequest`, `OpenRouterProvider`. +- Error handling: catch and propagate errors explicitly; do not swallow. +- Streaming: handle `useStreaming` flag to switch between full response and incremental data. +- Configuration: `OpenRouterProvider` should expose a singleton or factory pattern ensuring a single source of truth. +- Request retries: implement idempotent retries with exponential backoff if applicable. +- Use environment variables or secure storage for API keys; avoid hardcoding. +- Validate input parameters (`useStreaming`) before request execution. +- Maintain clear separation: request construction, execution, and response parsing. + +## Pitfalls +- Frequent modifications in `gpt-client.ts` and `makeRequest` increase risk of breaking request invariants; ensure thorough testing. +- Mismanaging streaming: not handling partial data or not aborting streams properly can cause leaks or inconsistent state. +- Hardcoded API keys or endpoints in `OpenRouterProvider.ts` can lead to security issues or misconfiguration. +- Forgetting to validate provider configuration before requests can cause runtime errors. +- Churn in core modules suggests instability; avoid making breaking changes without comprehensive tests. +- Overlooking error propagation from OpenAI responses may result in silent failures. +- Not respecting rate limits or API quotas can cause request failures; implement throttling if necessary. + +## Dependencies +- **OpenAI SDK:** Use the official OpenAI package for request formatting and response parsing. +- **Configuration Management:** Ensure `OpenRouterProvider.ts` supplies correct API keys and endpoint URLs. +- **Error Handling Libraries:** Use consistent error classes or handling patterns for API errors. +- **Environment Variables:** Securely load API keys and sensitive configs; avoid hardcoded secrets. +- **Streaming Support:** Handle Node.js streams or fetch API's streaming capabilities as per environment. + +--- + +**Note:** Always verify the latest API specifications and provider configurations, as frequent churn indicates evolving requirements or refactoring. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_addbeac5.md b/packages/app/server/src/AGENTS_this_cluster_manages_addbeac5.md new file mode 100644 index 000000000..0ef26df0c --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_addbeac5.md @@ -0,0 +1,50 @@ +# Semantic Cluster: Server Services and Client Integration + +## Purpose +This cluster manages server-side interactions with the Anthropic API, specifically encapsulating the logic for making streaming and non-streaming requests via the `makeRequest` function, and providing a `FreeTierService` that likely orchestrates usage limits or billing logic related to these interactions. + +## Boundaries +- **Belongs here:** + - All logic related to constructing, sending, and handling responses from the Anthropic API within `anthropic-client.ts`. + - Business logic managing free tier constraints or quotas within `FreeTierService.ts`. + - The `makeRequest` function's implementation details, including streaming behavior and error handling. +- **Does NOT belong here:** + - Client-side UI logic or presentation code. + - Authentication mechanisms for the API (unless embedded in the client). + - External data storage or caching layers—these should be abstracted or handled outside this cluster. + - Other service integrations unrelated to Anthropic or free tier management. + +## Invariants +- `makeRequest` must always handle the `useStreaming` boolean explicitly, defaulting to `true`. +- Response handling in `makeRequest` must correctly process streaming vs. non-streaming responses without resource leaks. +- `FreeTierService` should not exceed API quotas; enforce limits before making requests. +- All API calls via `anthropic-client.ts` must include necessary authentication headers or tokens, assumed to be configured externally. +- Null or undefined responses from the API must be gracefully handled, with proper error propagation or fallback logic. +- The code must maintain idempotency where applicable, especially in quota checks and request retries. + +## Patterns +- Use explicit boolean flags (`useStreaming`) to control request modes; avoid implicit assumptions. +- Follow consistent naming conventions: `makeRequest`, `FreeTierService`, `anthropic-client`. +- Error handling should be explicit, catching API errors, network failures, and streaming errors; do not rely on silent failures. +- When modifying `makeRequest`, respect the streaming pattern: process chunks as they arrive, and close streams properly. +- Encapsulate API request logic within `anthropic-client.ts`; do not duplicate request setup elsewhere. +- Maintain clear separation of concerns: `FreeTierService` handles quota logic, `anthropic-client.ts` handles API communication. + +## Pitfalls +- Modifying `makeRequest` without updating error handling or stream management can cause resource leaks or inconsistent states. +- Changing the default `useStreaming` flag without considering downstream effects may break consumers expecting streaming responses. +- Overlooking quota enforcement in `FreeTierService` can lead to exceeding free tier limits, causing billing issues or API throttling. +- Ignoring external dependencies (e.g., Anthropic) version updates may introduce incompatibilities; monitor dependency changelogs. +- Frequent modifications to `FreeTierService.ts`, `anthropic-client.ts`, and `makeRequest` suggest these are fragile; changes should be tested thoroughly, especially around error paths. +- Not handling null or unexpected API responses can cause runtime errors; always validate responses before processing. + +## Dependencies +- **External:** + - `Anthropic` SDK: Ensure correct usage per version; handle API key management securely. +- **Internal:** + - `FreeTierService`: Use it to check and enforce quota limits before making API requests. + - `anthropic-client.ts`: Use the exported client functions to send requests; do not reimplement request logic. +- **Usage:** + - Always initialize `makeRequest` with the correct `useStreaming` flag based on context. + - Confirm quota availability via `FreeTierService` before invoking `makeRequest`. + - Handle streaming responses asynchronously, respecting backpressure and chunk processing. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_baf24839.md b/packages/app/server/src/AGENTS_this_cluster_manages_baf24839.md new file mode 100644 index 000000000..7a551e84e --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_baf24839.md @@ -0,0 +1,55 @@ +# Semantic Cluster: Request Handling & GPT Integration (packages/app/server/src) + +## Purpose +This cluster manages the core logic for making external API requests, specifically to the VEO3 client and GPT providers, facilitating video generation workflows and AI interactions. It encapsulates request construction, execution, and response handling, abstracting external service communication. + +## Boundaries +- **Belongs here:** + - `makeRequest()` implementation, including request setup, retries, error handling. + - VEO3 client interactions (`veo3-client.ts`) for video-related API calls. + - GPTProvider logic for AI prompt management and response parsing. + - External dependencies `GenerateVideosOperation` and `GoogleGenAI` for video generation and AI services. +- **Does NOT belong here:** + - UI logic, user input validation, or frontend-specific code. + - Data persistence or database interactions. + - Authentication, authorization, or security concerns outside request context. + - Other service integrations unrelated to request execution or GPT/Video APIs. + +## Invariants +- `makeRequest()` must always handle errors gracefully, implementing retries or fallback strategies. +- Requests to `VEO3` and `GoogleGenAI` must include necessary authentication tokens, never omitted. +- Responses must be validated for expected structure; invalid responses should trigger explicit errors. +- `makeRequest()` should not mutate shared state; it must be stateless or manage internal state carefully. +- External API calls should respect rate limits; implement throttling if necessary. +- Null-safety: responses and parameters must be checked for null/undefined before processing. +- Order of operations: request setup → send → validate response → handle errors. + +## Patterns +- Use consistent naming conventions: `makeRequest()` as the core request executor, `VEO3Client`, `GPTProvider`. +- Error handling: catch exceptions, log detailed context, and propagate meaningful errors. +- Asynchronous flow: always `await` API calls; handle promise rejections explicitly. +- Request configuration: separate request construction from execution; use helper functions if needed. +- Modular design: keep `makeRequest()` generic, configurable for different endpoints and payloads. +- Use environment variables or config files for API keys/tokens, never hardcoded. +- Response validation: check for expected properties; throw descriptive errors if invalid. +- Churn-sensitive code: avoid complex logic inside `makeRequest()`; prefer simple, repeatable patterns. + +## Pitfalls +- Frequently modified `makeRequest()` risks introducing inconsistent error handling or request logic. +- Hardcoded API tokens or endpoints can cause security issues or bugs during environment changes. +- Neglecting response validation may lead to downstream errors or data corruption. +- Ignoring rate limits or retries can cause request failures or API bans. +- Coupling between `veo3-client.ts` and `GPTProvider.ts` may lead to tight dependencies, reducing flexibility. +- Not handling null/undefined responses can cause runtime exceptions. +- Overloading `makeRequest()` with multiple responsibilities (e.g., logging, retries, response parsing) increases churn and complexity. + +## Dependencies +- **GenerateVideosOperation:** Use for orchestrating video generation workflows; ensure correct invocation and response handling. +- **GoogleGenAI:** Leverage for AI prompt processing; manage API keys securely, handle rate limits. +- **External APIs:** Respect rate limits, handle network errors, validate responses. +- **Configuration:** Use environment variables for API keys, endpoints, timeouts. +- **Logging & Monitoring:** Instrument `makeRequest()` to capture request durations, failures, and retries for observability. + +--- + +**Note:** Focus on maintaining stateless, retryable, and validated request logic. Be vigilant about frequent modifications, ensuring consistent error handling and response validation to prevent subtle bugs. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_bf610cea.md b/packages/app/server/src/AGENTS_this_cluster_manages_bf610cea.md new file mode 100644 index 000000000..db5894f92 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_bf610cea.md @@ -0,0 +1,42 @@ +# Semantic Cluster: Request Lifecycle & Authentication Middleware (packages/app/server/src) + +## Purpose +This cluster manages request lifecycle handling, including setup of middleware for tracing, cleanup of orphaned requests, and management of in-flight request counts tied to user sessions within the authentication context. + +## Boundaries +- **Belongs here:** Middleware setup (`traceSetupMiddleware`), request cleanup (`cleanupOrphanedRequests`), in-flight request tracking (`decrementInFlightRequests`), and authentication services (`x402AuthenticationService.ts`). +- **Does NOT belong here:** Business logic unrelated to request tracking or authentication; database persistence beyond transient request state; UI rendering or client-side logic; external API integrations outside of authentication services. + +## Invariants +- `traceSetupMiddleware` must always assign a unique request ID (via `requestId` or `randomUUID`) and attach trace context to `req` for downstream logging/monitoring. +- `cleanupOrphanedRequests` must reliably identify and remove requests that have exceeded timeout or are no longer active, preventing memory leaks. +- `decrementInFlightRequests` must only be called after a successful request processing, ensuring in-flight count accurately reflects active requests per `(userId, echoAppId)` pair. +- All in-flight request counters must never become negative; decrement operations should check current count before decrementing. +- Middleware (`traceSetupMiddleware`) must call `next()` exactly once, and handle errors gracefully without disrupting request flow. +- Authentication service module (`x402AuthenticationService.ts`) must expose functions that maintain stateless or properly synchronized session info, avoiding race conditions. + +## Patterns +- Use `requestId` or `randomUUID` to generate unique request identifiers; consistently attach to `req` for tracing. +- Wrap `cleanupOrphanedRequests` and `decrementInFlightRequests` with try-catch blocks to prevent unhandled exceptions. +- When decrementing in-flight requests, verify existence before decrementing; avoid negative counts. +- Middleware (`traceSetupMiddleware`) should set trace context early, ensuring all subsequent logs have trace info. +- Use async/await with proper error handling; ensure `next()` is called exactly once per request. +- Maintain clear separation between request setup (trace, auth) and cleanup (orphaned requests, in-flight counts). + +## Pitfalls +- Forgetting to call `next()` in `traceSetupMiddleware` can halt request processing. +- Race conditions in `decrementInFlightRequests` may cause negative counters if not checked. +- Frequent modifications (5 versions) suggest instability; agents should verify consistency after updates. +- Improper cleanup in `cleanupOrphanedRequests` can cause memory leaks or stale request states. +- External dependencies (`requestId`, `transaction`) require correct initialization; misusing them can corrupt trace or transaction data. +- Over-incrementing in-flight requests without corresponding decrements leads to inaccurate request metrics. +- Tight coupling with authentication service (`x402AuthenticationService.ts`) requires understanding its session management assumptions. + +## Dependencies +- **External:** `randomUUID` (for unique ID generation), `requestId` (likely a request-scoped ID), `transaction` (for tracing or logging context). +- **Internal:** `x402AuthenticationService.ts` provides authentication-related functions; agents must understand its API to avoid misuse. +- **Usage:** Ensure `randomUUID` is used for request IDs only when `requestId` is unavailable; handle `transaction` context carefully to maintain trace continuity. + +--- + +**Note:** Agents should monitor frequent modifications to these components, as they indicate evolving patterns or instability. Always verify the latest version for subtle behavioral changes. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_c0159fcd.md b/packages/app/server/src/AGENTS_this_cluster_manages_c0159fcd.md new file mode 100644 index 000000000..764f613a4 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_c0159fcd.md @@ -0,0 +1,55 @@ +# Semantic Cluster: Server Request Handling & Authentication (packages/app/server/src) + +## Purpose +This cluster manages server-side request processing, specifically handling non-streaming responses, API key validation, and X402-specific authentication flows. It encapsulates logic for verifying requests, generating request IDs, and interfacing with external payment and authentication systems. + +## Boundaries +- **Belongs here:** Request lifecycle management (`handleNonStreaming`), API key retrieval (`getApiKey`), X402 authentication (`authenticateX402Request`, `identifyX402Request`, `identifyX402Transaction`), and associated response types (`VerifyResponse`, `X402PaymentBody`, etc.). +- **Does NOT belong:** Core business logic unrelated to request handling, database persistence, or UI rendering. Payment processing functions like `transfer` are part of transfer modules, not core request validation. Utility functions (e.g., `generateRequestId`, `getRequestId`) are helpers but should be used consistently within request flow. + +## Invariants +- `handleNonStreaming` must always send a response or throw an error; no silent failures. +- `getApiKey()` may return `undefined`; callers must handle absence explicitly. +- Authentication methods (`authenticateX402Request`, `identifyX402Request`, `identifyX402Transaction`) must be called in sequence to establish trust; their results are stateful and should not be reused across different requests without re-validation. +- `generateRequestId()` and `getRequestId()` must produce unique, collision-resistant IDs; `generateRequestId()` should be invoked per request, `getRequestId()` retrieves the current request’s ID. +- External dependencies (`uuidv4`, `encodeFunctionData`) are critical for ID generation and contract data encoding; must be used correctly to prevent collisions or malformed data. +- External modules (`constants.ts`, `transferWithAuth.ts`) should be imported only for their defined constants and functions, avoiding side effects or global state assumptions. +- All interfaces (`VerifyResponse`, `X402PaymentBody`, `Balance`, etc.) are versioned; modifications must preserve backward compatibility unless explicitly versioned. + +## Patterns +- Use `async/await` consistently for all I/O-bound operations. +- Validate presence of `ApiKey` before proceeding; handle `undefined` gracefully. +- When handling X402 requests, always invoke `identifyX402Request` and `identifyX402Transaction` in sequence, ensuring proper request context. +- Generate request IDs at the start of request processing (`generateRequestId`) and store/retrieve via `getRequestId`. +- Follow naming conventions: methods prefixed with `get` for accessors, `identify` for request context, `authenticate` for security checks. +- Handle errors explicitly; do not assume external calls succeed. +- Use dependency injection for external modules where possible to facilitate testing and mocking. +- Maintain strict null-safety: check for `null` or `undefined` before dereferencing objects like `echoApp`, `markUp`, or `authResult`. +- For payment and transaction-related interfaces, ensure data integrity before processing. + +## Pitfalls +- **Churn-prone methods (`handleNonStreaming`, `getApiKey`)** are frequently modified; introduce regressions or inconsistent behavior. +- **Authentication flow** is complex; missing sequence calls or improper validation can lead to security vulnerabilities. +- **Request ID generation** is critical; reuse or collision can cause traceability issues. +- **External dependencies** like `uuidv4` and `encodeFunctionData` are sensitive; incorrect usage leads to malformed IDs or contract data. +- **Versioned interfaces** (`VerifyResponse`, `X402PaymentBody`, etc.) require careful updates; incompatible changes break consumers. +- **Null/undefined handling** is often overlooked, risking runtime errors. +- **Frequent modifications** to core methods (`handleNonStreaming`, `getApiKey`) increase risk of introducing bugs or inconsistencies. + +## Dependencies +- **External:** + - `uuidv4`: Use for generating collision-resistant, unique request IDs. Call once per request, avoid reusing IDs. + - `encodeFunctionData`: Use for encoding contract function calls; ensure correct ABI and data formatting. + - `Decimal`: Use for precise financial calculations; avoid floating-point inaccuracies. +- **Internal:** + - `constants.ts`: Source of configuration constants; import explicitly, avoid side effects. + - `transferWithAuth.ts`: Contains transfer logic with authentication; invoke with correct parameters, handle errors. +- **Function Calls:** + - `getSmartAccount`: Called by dependent modules; ensure it’s available and correctly initialized. + - `getEchoApp`, `getAuthResult`: Retrieve context objects; check for nulls before use. + - `generateRequestId`, `getRequestId`: Use for request tracking; maintain consistency. + - `authenticateX402Request`, `identifyX402Request`, `identifyX402Transaction`: Chain these calls for secure, authenticated request processing. + +--- + +**Note:** AI agents must prioritize security, null-safety, and consistent ID management when working within this cluster. Changes to frequently modified methods require rigorous testing to prevent regressions. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_c20b1a1b.md b/packages/app/server/src/AGENTS_this_cluster_manages_c20b1a1b.md new file mode 100644 index 000000000..df98cbaf2 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_c20b1a1b.md @@ -0,0 +1,59 @@ +# Semantic Cluster: GPT Provider and Streaming Parsing (packages/app/server/src) + +## Purpose +This cluster manages multiple GPT provider implementations (OpenAI, Anthropic, Gemini), handles streaming response parsing, and computes token costs. It encapsulates provider-specific logic, response handling, and format parsing, enabling flexible, multi-provider LLM interactions with robust streaming support. + +## Boundaries +- **Belongs here:** Provider classes (`GPTProvider`, `AnthropicGPTProvider`, `GeminiGPTProvider`), response parsing functions (`parseSSEGPTFormat`, `parseSSEAnthropicGPTFormat`, `parseSSEGeminiFormat`, etc.), `handleBody` methods, token cost calculations (`getCostPerToken`), and related interfaces (`StreamingChunkBody`, `Transaction`, `TransactionMetadata`, etc.). +- **Does NOT belong here:** UI components, client-side streaming management, high-level orchestration outside provider context, or unrelated domain logic. Infrastructure concerns like network transport, auth, or logging are outside scope unless directly invoked here. + +## Invariants +- `handleBody` methods must always return a `Transaction` object; handle errors gracefully, do not throw unhandled exceptions. +- Streaming data formats (SSE) must be parsed with their respective functions; mismatched formats lead to null or errors. +- `super()` calls in provider classes must match the expected constructor signatures; frequent modifications to `super()` imply fragile inheritance chains. +- Token cost calculations via `getCostPerToken` must consider model-specific pricing; invalid models should trigger `UnknownModelError`. +- Response parsing functions (`parseSSE*Format`) must produce consistent `StreamingChunkBody` objects; malformed data should result in null or handled errors. +- `getApiKey()` must return undefined if no key is configured; avoid nulls. +- All provider classes extend `OpenAIBaseProvider`, inheriting its contract; ensure overridden methods conform to expected behavior. + +## Patterns +- Use `async handleBody(data: string)` consistently for streaming response handling; always return a `Transaction`. +- Parsing functions follow a pattern: receive raw string, parse into structured objects, handle errors internally, return arrays or null. +- `super()` calls are frequently versioned; maintain correct constructor signatures and document version dependencies. +- Token cost calculation via `getCostPerToken` is externalized; always pass correct model identifiers and token counts. +- Provider classes implement `getType()` returning a `ProviderType`; ensure correct enum usage. +- Interfaces define clear contracts; implementers must adhere to `TransactionMetadata` extensions. +- Use `getApiKey()` to retrieve credentials; handle undefined safely. +- Modularize parsing logic per format (`SSEGPT`, `SSEAnthropicGPT`, `SSEGemini`) to isolate format-specific quirks. +- Maintain strict null-safety and validation in response parsing to avoid downstream errors. + +## Pitfalls +- **Frequent `super()` modifications:** Risk of constructor signature mismatches; verify all subclasses call `super()` with correct parameters. +- **Churn in `LlmTransactionMetadata`:** High dependency count increases risk of inconsistent metadata handling; ensure all consumers correctly interpret metadata. +- **`getCostPerToken` reliance:** Heavy external dependency; incorrect model names or token counts can produce inaccurate costs, affecting billing logic. +- **Streaming format parsing:** Mismatched or malformed SSE data can cause silent failures or incorrect `StreamingChunkBody` objects; validate data before parsing. +- **Response handling in `handleBody`:** Failure to handle exceptions or unexpected data formats can crash or produce invalid transactions. +- **Versioned `super()` calls:** Frequent modifications suggest fragile inheritance; avoid unnecessary changes and document version dependencies. +- **High coupling with external modules:** Calls to `logMetric`, `UnknownModelError`, `isValidModel`, `getModelPrice` imply tight coupling; ensure these are stable and correctly used. +- **Churn hotspots:** Frequent updates to `super()` and `LlmTransactionMetadata` indicate areas prone to regressions; test thoroughly when modifying. +- **Error propagation:** Avoid unhandled errors in parsing and response handling; always catch and log errors internally. + +## Dependencies +- **External:** `Decimal`, `array`, `tokens` for precise calculations, array manipulations, and token management. +- **Internal references:** + - `Transaction` (core data structure for responses) + - `handleBody` (response handler pattern) + - `getBaseUrl`, `logMetric`, `UnknownModelError`, `isValidModel`, `getModelPrice` (utility functions for metrics, validation, pricing) + - `OpenAIBaseProvider` (base class for providers) + - `TransactionMetadata` and extensions (`VeoTransactionMetadata`, `LlmTransactionMetadata`) for metadata handling. +- **Dependencies of this cluster:** + - References `Transaction` and related metadata interfaces. + - Calls `handleBody`, `getBaseUrl`, `logMetric`, `UnknownModelError`, `isValidModel`, `getModelPrice`. + - Extends `OpenAIBaseProvider`. +- **Dependent on by:** + - Higher-level routing or orchestration modules (`trpc/routers/user/index.ts`), other provider-specific modules (`AnthropicNativeProvider`), and utility functions (`createBuckets`, `isLlmTransactionMetadata`, `isVeoTransactionMetadata`). + +--- + +**Summary:** +This cluster encapsulates provider-specific streaming response handling, format parsing, and token cost calculation. Agents must respect constructor invariants, handle streaming formats robustly, and be aware of frequent `super()` modifications. External dependencies for metrics, validation, and pricing are critical; misusing them risks incorrect billing or unstable behavior. Maintain strict adherence to response contracts, parsing patterns, and error handling to ensure stability amidst high churn areas. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_c25e1ea5.md b/packages/app/server/src/AGENTS_this_cluster_manages_c25e1ea5.md new file mode 100644 index 000000000..ccb3314fc --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_c25e1ea5.md @@ -0,0 +1,46 @@ +# Semantic Cluster: Server Middleware and GPT Client Integration + +## Purpose +This cluster manages request tracing enrichment via `trace-enrichment-middleware.ts`, handles GPT API interactions through `makeRequest`, and interfaces with the Gemini GPT client. It enables enriched request context propagation and external AI service communication within the server. + +## Boundaries +- **Belongs here:** Middleware for trace enrichment, GPT request logic, client wrapper for Gemini GPT API. +- **Does NOT belong here:** UI components, frontend request handling, unrelated external APIs, or unrelated internal modules. Business logic unrelated to request tracing or GPT interactions should be elsewhere. + +## Invariants +- `trace-enrichment-middleware.ts` must always attach consistent trace context to requests; do NOT omit or overwrite existing context. +- `makeRequest` must handle `useStreaming` flag correctly; streaming mode should be explicitly enabled and managed. +- All GPT requests via `gemini-gpt-client.ts` must include proper API keys, handle rate limits, and respect OpenAI's usage policies. +- `makeRequest` must never proceed with null/undefined parameters; enforce input validation. +- Resources (e.g., streams, connections) opened during GPT requests must be properly closed or cleaned up to prevent leaks. +- Request IDs and trace context must be propagated synchronously; asynchronous modifications risk losing context. + +## Patterns +- Use consistent naming: `makeRequest`, `trace-enrichment-middleware`. +- Error handling: Catch and log errors explicitly; do not swallow exceptions silently. +- For `makeRequest`, prefer explicit boolean flags (`useStreaming`) over implicit assumptions. +- Middleware should attach trace info at the earliest point in the request lifecycle. +- External dependencies (`OpenAI`, `next`) must be imported and used according to their latest API specifications. +- When modifying `makeRequest`, preserve the pattern of returning a promise that resolves with the response or rejects with an error. +- Use environment variables or configuration files for API keys and endpoints; avoid hardcoding sensitive info. + +## Pitfalls +- Frequently modified files (`trace-enrichment-middleware.ts`, `makeRequest`, `gemini-gpt-client.ts`) are prone to introducing regressions; test trace propagation and GPT request flows thoroughly. +- Mistakes in trace context propagation can lead to broken request tracing, making debugging difficult. +- In `makeRequest`, neglecting to handle streaming properly can cause resource leaks or incomplete data handling. +- Overlooking rate limits or API quota constraints in `gemini-gpt-client.ts` may cause request failures. +- Inconsistent error handling patterns can obscure root causes of failures. +- Modifying `useStreaming` without understanding its impact on downstream consumers can break data flow. +- Changes in external dependencies (`OpenAI`, `next`) require updating code to match new APIs; failure to do so causes runtime errors. +- High churn areas suggest frequent updates; extra caution needed to prevent introducing bugs during refactoring. + +## Dependencies +- **OpenAI SDK:** Use latest API version; ensure API keys are securely managed via environment variables. +- **Next.js:** Leverage its request/response lifecycle for middleware; respect its data-fetching patterns. +- **Internal modules:** Maintain compatibility with existing trace context propagation and request handling conventions. +- **External APIs:** Follow rate limiting, quota, and error handling guidelines; implement retries if necessary. +- **Logging/Monitoring:** Integrate with existing observability tools to track errors and request flow, especially around `trace-enrichment-middleware.ts` and `makeRequest`. + +--- + +**Note:** Always verify that modifications preserve existing invariants, especially around trace context integrity and GPT request correctness. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_de9224a2.md b/packages/app/server/src/AGENTS_this_cluster_manages_de9224a2.md new file mode 100644 index 000000000..4edad14a7 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_de9224a2.md @@ -0,0 +1,49 @@ +# Semantic Cluster: Provider and Service Management (packages/app/server/src) + +## Purpose +This cluster manages provider types, executes model requests, verifies video access, and orchestrates echo and earnings services. It encapsulates core business logic for provider handling, user usage validation, and service configuration. + +## Boundaries +- **Belongs here:** Provider type retrieval (`getType()`), model request execution (`executeModelRequest`), video access verification (`verifyVideoAccess`), echo control configuration (`setEchoControlService`), and user usage checks (`checkExistingUserUsage`, `checkValidFreeTierSpendPool`, `getOrNoneFreeTierSpendPool`). +- **Does NOT belong here:** Authentication logic (handled in `auth/index.ts`), external API integrations (e.g., GeminiVeoProvider, checkBalance), database schema definitions (handled by Prisma models), or HTTP layer concerns (e.g., request/response handling outside `executeModelRequest`). + +## Invariants +- `getType()` must consistently return the correct `ProviderType` for the provider instance; mismatches can cause downstream errors. +- `executeModelRequest()` must always handle `req`, `res`, and `processedHeaders` atomically; partial failures should trigger proper error handling via `HttpError`. +- `verifyVideoAccess()` should throw if access is invalid; never silently fail or grant access. +- `setEchoControlService()` must only assign a valid `EchoControlService` instance; null or undefined assignments should be guarded against. +- Constructors must initialize all dependencies (`db`, `model`, optional `echoControlService`) before use; no uninitialized state. +- Usage validation functions (`checkExistingUserUsage`, `checkValidFreeTierSpendPool`) must enforce limits strictly; no bypasses. +- `getOrNoneFreeTierSpendPool()` should return `null` if no free tier pool exists, not throw. +- External dependencies like `HttpError` and `transaction` must be used within their intended contexts; misuse can cause resource leaks or inconsistent states. + +## Patterns +- Use explicit dependency injection via constructors for services (`EchoControlService`, `PrismaClient`). +- Consistently handle asynchronous operations with `async/await`. +- Error handling should leverage `HttpError` for HTTP-related failures. +- Naming conventions: methods prefixed with `get` for retrieval, `check` for validation, `set` for configuration. +- When modifying `getType()`, ensure all implementations return a `ProviderType` enum value; avoid returning undefined or inconsistent types. +- For `executeModelRequest`, follow the pattern of passing `processedHeaders` explicitly, ensuring header integrity. +- Use `Promise`-based return types for all async methods that may fail or involve I/O. +- Maintain separation of concerns: core logic in service classes, external calls in dedicated modules. + +## Pitfalls +- **High churn methods (`getType()`, `executeModelRequest`, `verifyVideoAccess`, `setEchoControlService`)**: frequent modifications risk introducing inconsistencies or breaking invariants. +- **EchoControlService dependency**: dependency on 7 external entities increases coupling; modifications can ripple unexpectedly. +- **Null-safety**: constructors with optional `echoControlService` require null checks before usage. +- **Concurrency issues**: `executeModelRequest` may involve streaming; ensure proper handling of stream lifecycle and errors. +- **Usage validation**: `checkExistingUserUsage` and `checkValidFreeTierSpendPool` must be strict; lax validation leads to resource abuse. +- **Frequent code changes**: methods like `getType()` are highly volatile; avoid assumptions based on previous versions. +- **Resource management**: `transaction` usage must be properly committed or rolled back; improper handling leads to data inconsistency. +- **External dependency reliance**: `HttpError`, `transaction`, and `verifyUserHeaderCheck` are critical; misuse can cause security or stability issues. + +## Dependencies +- **References:** `X402AuthenticationResult`, `ApiKeyValidationResult`, `Transaction` — ensure correct data flow and validation. +- **Calls:** `HttpError` for error handling; use consistently for HTTP failures. +- **External modules:** `Decimal` for precise calculations, `existsSync`, `join` for filesystem checks, `transaction` for DB atomicity, `verifyUserHeaderCheck` for header validation. +- **Usage notes:** Always validate headers with `verifyUserHeaderCheck` before processing requests; use `transaction` for any database modifications involving multiple steps to ensure atomicity. +- **Dependent entities:** `BaseProvider`, `GeminiVeoProvider`, `EscrowRequest`, `X402AuthenticationService`, `checkBalance` — understand their interfaces and side effects for correct integration. + +--- + +**Note:** Agents should monitor high-churn methods closely, enforce strict validation, and be cautious with dependency updates to prevent regressions. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_dff8083f.md b/packages/app/server/src/AGENTS_this_cluster_manages_dff8083f.md new file mode 100644 index 000000000..4ee29111a --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_dff8083f.md @@ -0,0 +1,47 @@ +# Cleanup and API Key Management + +## Purpose +This cluster manages the cleanup routines for server-side resources and updates metadata related to API key usage, ensuring resource hygiene and accurate tracking of API key activity within the application. + +## Boundaries +- **Belongs here:** + - Implementation of scheduled cleanup processes (`startCleanupProcess`) + - Updating last-used timestamps for API keys (`updateApiKeyLastUsed`) + - Transactional database operations involving API key metadata +- **Does NOT belong here:** + - User authentication or authorization logic + - External API integrations outside of internal database updates + - Non-cleanup related background jobs or scheduled tasks unrelated to resource cleanup or API key tracking + +## Invariants +- `startCleanupProcess` must be idempotent; repeated invocations should not cause inconsistent state or errors. +- `updateApiKeyLastUsed` must be called within an active Prisma transaction (`tx`) to ensure atomicity; do not call outside a transaction context. +- API key last-used timestamps must never be set to null or invalid dates; enforce non-null, valid Date objects. +- Cleanup process should not delete or modify resources that are actively in use or marked as protected; implement safeguards or flags to prevent accidental deletion. +- All database updates via Prisma transactions should handle errors gracefully, rolling back on failure to maintain consistency. + +## Patterns +- Use explicit transaction management: always pass a `Prisma.TransactionClient` (`tx`) to `updateApiKeyLastUsed`. +- Follow naming conventions: methods prefixed with `start` for initiating processes, `update` for state changes. +- Handle errors explicitly within `startCleanupProcess`, ensuring cleanup failures do not leave the system in inconsistent states. +- Use consistent timestamp formats and ensure timezone-awareness if applicable. +- Document assumptions about resource states before cleanup or update operations. + +## Pitfalls +- **Churn:** Both methods are frequently modified; avoid introducing complex logic without thorough testing. +- **Concurrency:** `updateApiKeyLastUsed` relies on transactional safety; avoid calling it outside a transaction or in parallel without proper locking. +- **Resource leaks:** `startCleanupProcess` may inadvertently leave resources uncleaned if error handling is incomplete. +- **Null safety:** Ensure `apiKeyId` is validated before use; null or malformed IDs can cause silent failures or data corruption. +- **Side effects:** Be cautious of side effects within cleanup routines; unintended deletions or updates can cause data loss. + +## Dependencies +- **Prisma ORM:** + - Use the provided `tx` transaction client for all database operations to ensure atomicity. + - Validate transaction state before performing updates. +- **Database schema assumptions:** + - `apiKeyId` corresponds to a valid API key record. + - Timestamps are stored in a consistent, timezone-aware format. +- **Error handling:** + - Implement try-catch blocks within `startCleanupProcess` to handle and log failures without crashing the process. + - Ensure `updateApiKeyLastUsed` is called only within a successful transaction context. +- **No external dependencies** are directly involved; rely solely on Prisma and internal database schema. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_e9ad80a2.md b/packages/app/server/src/AGENTS_this_cluster_manages_e9ad80a2.md new file mode 100644 index 000000000..409cadb8b --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_e9ad80a2.md @@ -0,0 +1,43 @@ +# [Semantic Cluster: Resource Handling & Cost Calculation in Server Router] + +## Purpose +This cluster manages resource-related HTTP routes (`tavilyExtractRoute`, `tavilySearchRoute`, `e2bExecuteRoute`, `tavilyCrawlRoute`) and associated cost calculations, providing a structured API for resource extraction, search, execution, and crawling within the server. It encapsulates request handling, error management, and cost estimations critical for resource operations. + +## Boundaries +- **Belongs here:** Route handlers (`tavilyExtractRoute`, `tavilySearchRoute`, `e2bExecuteRoute`, `tavilyCrawlRoute`), cost calculation functions, `handleResourceRequestWithErrorHandling`, `getEchoAppId`, and `ResourceHandlerConfig`. +- **Does NOT belong here:** Database schema definitions, core business logic unrelated to resource routes, UI components, or client-side code. Any non-resource-specific middleware or authentication logic should be outside this cluster. + +## Invariants +- `handleResourceRequestWithErrorHandling` must always wrap route handlers, ensuring consistent error handling and request validation. +- `getEchoAppId()` may return `null`; callers must handle null safely. +- Cost calculation functions (`calculateTavilySearchCost`, `calculateE2BExecuteCost`, etc.) must receive valid input objects or `undefined`, returning a `Decimal` that accurately reflects the cost; no negative or nonsensical values. +- Route functions (`tavilyExtractRoute`, etc.) should always invoke `handleResourceRequestWithErrorHandling` internally or follow its pattern to maintain uniform error management. +- `constructor` must initialize with a valid `PrismaClient`; no null or undefined allowed. +- External dependencies (`Decimal`, `Router`, `parameter`) are assumed to be correctly imported and used per their documentation. + +## Patterns +- Use `handleResourceRequestWithErrorHandling` as the wrapper for all route handlers to standardize error catching. +- Route functions should extract parameters explicitly, validate inputs, and pass them to cost functions or core logic. +- Cost functions should handle `undefined` inputs gracefully, returning a meaningful `Decimal`. +- Naming conventions: route handlers prefixed with `tavily` or `e2b`, cost functions with `calculate` prefix. +- Use `getEchoAppId()` to retrieve app context; handle `null` cases explicitly. +- Consistently use `Decimal` for monetary or cost calculations to avoid floating-point inaccuracies. +- Maintain statelessness in route handlers; rely on request parameters and external dependencies only. + +## Pitfalls +- Failing to handle `null` from `getEchoAppId()` can cause runtime errors downstream. +- Modifying frequently changed functions (`getEchoAppId`, constructor, route handlers) without updating dependent logic risks breaking invariants. +- Not wrapping route handlers with `handleResourceRequestWithErrorHandling` leads to inconsistent error responses. +- Cost functions accepting `undefined` but not handling it internally may produce incorrect costs; always validate inputs. +- Overlooking the `Decimal` type's constraints (precision, scale) may cause subtle bugs in cost calculations. +- Ignoring the high churn in core functions increases risk of regressions; changes should be tested thoroughly. +- External dependencies (`parameter`, `e2bExecutePythonSnippet`) require correct configuration; misusing them can cause runtime failures. + +## Dependencies +- **External:** `Decimal` (for precise cost calculations), `Router` (for route definitions), `parameter` (for parameter parsing), `e2bExecutePythonSnippet` (for executing Python snippets in `e2bExecuteRoute`). +- **Internal:** `handleResourceRequestWithErrorHandling` (wraps route handlers), `HttpError` (for error responses), `ResourceHandlerConfig` (configures request handling), `getEchoAppId` (context retrieval), `constructor` (initializes database connection). +- **Usage notes:** Always ensure `Decimal` is used for all cost-related functions to maintain precision. Use `parameter` to parse and validate request parameters before processing. + +--- + +This node captures the deep, non-obvious knowledge necessary for AI agents to understand the resource handling and cost calculation logic, ensuring robust, consistent modifications and integrations. \ No newline at end of file diff --git a/packages/app/server/src/AGENTS_this_cluster_manages_efaceb0d.md b/packages/app/server/src/AGENTS_this_cluster_manages_efaceb0d.md new file mode 100644 index 000000000..81e66d919 --- /dev/null +++ b/packages/app/server/src/AGENTS_this_cluster_manages_efaceb0d.md @@ -0,0 +1,54 @@ +# Semantic Cluster: Path Utilities & Spend Pool Management + +## Purpose +This cluster manages string manipulation related to model paths and updates the total spent amount in a spend pool, ensuring data consistency during transactional operations. It encapsulates path parsing logic and financial state mutation within the application's backend. + +## Boundaries +- **Includes:** + - Path string parsing logic specific to model directory structures (`extractPathAfterModels`). + - Atomic updates to the `totalSpent` field of a spend pool within a Prisma transaction (`updateSpendPoolTotalSpent`). + +- **Excludes:** + - General path validation or sanitization unrelated to "models" directory structure. + - Non-transactional or batch updates to spend pools. + - Business logic beyond updating `totalSpent` (e.g., spend pool creation, deletion, or complex financial calculations). + - External API calls or integrations outside Prisma transaction context. + +## Invariants +- `extractPathAfterModels` must always return the substring following the first occurrence of `/models/` in the input path; if absent, return the original path. +- `updateSpendPoolTotalSpent` must be executed within a Prisma transaction (`tx`) to ensure atomicity. +- The `amount` parameter in `updateSpendPoolTotalSpent` must be a `Decimal` and should not be negative; negative amounts may indicate refunds or corrections, but this invariant must be enforced outside this function. +- The `spendPoolId` must correspond to an existing spend pool; the function assumes validation occurs upstream. +- No side effects or external state mutations occur outside the provided transaction context. + +## Patterns +- Use consistent string splitting or regex in `extractPathAfterModels` to reliably parse paths. +- Always invoke `updateSpendPoolTotalSpent` within a Prisma transaction to prevent partial updates. +- Validate `amount` before calling `updateSpendPoolTotalSpent`; handle potential `Decimal` conversion errors explicitly. +- Follow naming conventions: methods prefixed with `extract` or `update`, parameters clearly typed, async functions properly awaited. +- Error handling should propagate exceptions; do not swallow Prisma errors or path parsing errors silently. + +## Pitfalls +- `extractPathAfterModels` is frequently modified; ensure changes preserve correct substring extraction logic to avoid incorrect path parsing. +- Chaining multiple string operations without null checks can cause runtime errors if input paths are malformed. +- `updateSpendPoolTotalSpent` relies on a valid Prisma transaction; calling outside a transaction or with an invalid `tx` object causes inconsistent state. +- Negative or zero `amount` values should be validated outside; the function assumes correctness. +- Churn hotspots indicate potential instability; changes may introduce bugs if not carefully tested, especially in path parsing logic. +- External dependencies are minimal, but incorrect usage of Prisma transaction client or Decimal can cause runtime exceptions. + +## Dependencies +- **Prisma Client:** + - Use the provided `tx` (transaction client) to perform atomic updates. + - Ensure `tx` is a valid Prisma transaction context; do not instantiate or reuse outside transaction scope. + +- **Decimal Library:** + - `amount` must be a `Decimal`; validate and convert inputs before invoking `updateSpendPoolTotalSpent`. + - Avoid floating-point inaccuracies by always using `Decimal` for monetary values. + +- **Path String Handling:** + - No external libraries; rely on robust string methods or regex for path parsing in `extractPathAfterModels`. + - Confirm path format consistency to prevent parsing errors. + +--- + +**Note:** Both methods are critical for maintaining data integrity and consistent path handling. Changes should be accompanied by thorough testing, especially around string parsing edge cases and transactional updates. \ No newline at end of file diff --git a/packages/app/server/src/__tests__/AGENTS_defines_a_test_08895faf.md b/packages/app/server/src/__tests__/AGENTS_defines_a_test_08895faf.md new file mode 100644 index 000000000..1499ee981 --- /dev/null +++ b/packages/app/server/src/__tests__/AGENTS_defines_a_test_08895faf.md @@ -0,0 +1,41 @@ +# setupMockEchoControlService Function + +## Purpose +Defines a test utility to instantiate a mocked `EchoControlService` with a configurable `balance` (default 100), used to simulate and control echo responses during unit tests. + +## Boundaries +- **Belongs here:** Only test setup code related to mocking `EchoControlService`; no production logic. +- **Does NOT belong here:** Actual service implementation, production code, or test cases unrelated to mocking setup. Avoid placing business logic or assertions in this function. + +## Invariants +- The `balance` parameter defaults to 100 if unspecified; callers must explicitly set or rely on default. +- The function always returns an instance of `MockedEchoControlService` configured with the provided `balance`. +- The mocked service's methods (e.g., `request`) should be stubbed/stubable to simulate various behaviors; ensure no side effects leak between tests. +- The function should not modify external state; it should produce a fresh mock instance each call. +- The `request` method of the mock should be properly stubbed to return predictable responses, respecting the test scenario. + +## Patterns +- Use consistent naming: `setupMockEchoControlService`. +- Always initialize the mock with explicit configuration; prefer default parameters for simplicity. +- When modifying, ensure the mock's `request` method is stubbed with a predictable, test-specific behavior. +- Follow test setup conventions: call `beforeEach` to initialize mocks, avoid global state mutation. +- Use dependency injection patterns to replace real services with mocks during tests. + +## Pitfalls +- **Churn:** The function is frequently modified (5 versions), risking inconsistent mock configurations. +- **Incorrect `balance`:** Forgetting to set or override `balance` can lead to misleading test results. +- **Shared state:** Reusing mock instances across tests can cause flaky tests; always instantiate fresh. +- **Stub leakage:** Not properly stubbing `request` can cause tests to pass/fail unpredictably. +- **Ignoring default:** Relying on default `balance` without explicitness can hide test intent. +- **Coupling to implementation:** Changes in `MockedEchoControlService` or `request` signature require updates here. + +## Dependencies +- **MockedEchoControlService:** Instantiate and configure with `balance`. +- **request:** Mocked method on the service; ensure proper stubbing in tests. +- **Testing Framework:** Use `beforeEach`, `describe`, `it`, `expect` for test lifecycle and assertions. +- **Streams and Encoders:** Imported but not directly used here; ensure correct handling if extended. +- **Type Safety:** Maintain correct types for `balance` and returned mock instances; avoid type mismatches. + +--- + +*Note:* When modifying `setupMockEchoControlService`, verify the mock's behavior aligns with test expectations, especially regarding `balance` and `request`. Keep the mock isolated and predictable to ensure reliable unit tests. \ No newline at end of file diff --git a/packages/app/server/src/__tests__/AGENTS_provides_utility_fun_264ce8b8.md b/packages/app/server/src/__tests__/AGENTS_provides_utility_fun_264ce8b8.md new file mode 100644 index 000000000..6c5fee003 --- /dev/null +++ b/packages/app/server/src/__tests__/AGENTS_provides_utility_fun_264ce8b8.md @@ -0,0 +1,53 @@ +# Mock Response and Headers Utilities (packages/app/server/src/__tests__) + +## Purpose +Provides utility functions to generate mock responses, headers, and streaming responses for testing server-side API interactions, particularly with AI model responses and control services. + +## Boundaries +- **Belongs here:** Functions creating mock responses (`createMockNonStreamingResponse`, `createMockAnthropicResponse`, `createMockStreamingResponse`, `createMockAnthropicStreamingResponse`), mock headers (`createMockHeaders`), and setup for echo control service (`setupMockEchoControlService`). +- **Does NOT belong here:** Actual production response handling, real network request logic, or integration with real services. These are strictly for testing and mocking. + +## Invariants +- Mock response functions must accept `content` and `totalTokens`, with `totalTokens` defaulting to 10. +- Streaming responses (`createMockStreamingResponse`, `createMockAnthropicStreamingResponse`) must return a `ReadableStream` that emits the provided `content`. +- `createMockHeaders` must produce a headers array compatible with fetch API expectations. +- `setupMockEchoControlService` initializes the mocked echo control service with a default or specified `balance`. +- All mock functions should be deterministic and produce consistent outputs for given inputs. +- Mocked responses should not accidentally include real network calls; they are purely in-memory constructs. +- Churn is high; frequent modifications suggest evolving test needs or response formats. + +## Patterns +- Use consistent parameter naming: `content`, `totalTokens`, `headers`, `balance`. +- Streaming responses should utilize `ReadableStream` with proper chunking. +- Mock responses should mimic real API responses closely, including headers and token counts. +- Setup functions (`setupMockEchoControlService`) should initialize shared state reliably before tests. +- Maintain clear separation between mock creation functions and setup functions. +- Follow naming conventions: functions prefixed with `createMock` for response mocks, `setupMock` for setup routines. +- Error handling is minimal; assume inputs are valid, but document if invalid inputs are possible. + +## Pitfalls +- Frequent modifications increase risk of inconsistent mock behaviors; document expected response structures. +- Churned functions like `createMockNonStreamingResponse` and streaming variants are prone to divergence; ensure they stay aligned. +- Over-reliance on default `totalTokens` may cause test inaccuracies if token counts are critical. +- Streaming responses must correctly implement backpressure and chunk emission; improper implementation leads to flaky tests. +- Be cautious with `setupMockEchoControlService`; improper initialization can cause state leakage between tests. +- Avoid mixing real network calls with mocks; ensure all dependencies are properly mocked. +- Null safety: ensure all mock functions handle empty or null `content` gracefully if such cases are tested. + +## Dependencies +- **External Modules:** + - `MockedEchoControlService`: used to initialize the echo control state; must be correctly instantiated and reset per test. + - `Provider`: for dependency injection if used elsewhere. + - `ReadableStream`: for creating streaming mock responses; ensure compatibility with test environment. + - `TextEncoder`: for encoding string content into stream chunks. +- **Internal:** + - `request`: mock or stubbed request function, used to simulate network calls if needed. +- **Usage notes:** + - Always call `setupMockEchoControlService` before tests that depend on echo control state. + - Use `createMockHeaders` to generate headers that match expected API responses. + - For streaming responses, verify chunk emission timing and content integrity. + - Maintain consistency in token count calculations if tests depend on `totalTokens`. + +--- + +**Note:** Given the high churn, keep documentation updated with each change to ensure test reliability and clarity for future modifications. \ No newline at end of file diff --git a/packages/app/server/src/__tests__/AGENTS_this_module_contains_72f6ca1b.md b/packages/app/server/src/__tests__/AGENTS_this_module_contains_72f6ca1b.md new file mode 100644 index 000000000..e724715a0 --- /dev/null +++ b/packages/app/server/src/__tests__/AGENTS_this_module_contains_72f6ca1b.md @@ -0,0 +1,44 @@ +# Server Test Module (packages/app/server/src/__tests__/server.test.ts) + +## Purpose +This module contains unit and integration tests for the server component, validating core functionalities, API endpoints, and internal logic to ensure correctness and stability during development and refactoring. + +## Boundaries +- **Belongs here:** Tests for server logic, API routes, middleware, and internal modules directly related to server behavior. +- **Does NOT belong here:** Implementation code, configuration files, or tests for unrelated modules (e.g., frontend, database schemas). Test fixtures or mocks should be minimal and specific to server logic. + +## Invariants +- Tests should not depend on external systems unless explicitly mocked. +- Test setup/teardown must cleanly initialize and dispose resources to prevent side effects. +- Test cases must be deterministic; avoid flaky tests caused by timing or external dependencies. +- Test data should be isolated; no shared mutable state across tests. +- Test execution order should be non-dependent; tests must be independent and idempotent. +- Error handling within tests must explicitly verify failure modes, not assume success. + +## Patterns +- Use consistent naming conventions for test descriptions: "should [expected behavior] when [condition]". +- Follow the Arrange-Act-Assert pattern strictly. +- Mock external dependencies explicitly; use dedicated mock modules or libraries. +- Use descriptive assertions; avoid generic `expect(true).toBe(true)`. +- Maintain clear separation between setup, execution, and verification phases. +- Use test-specific configurations or environment variables to isolate test environment. +- When modifying, preserve test isolation; avoid shared state or side effects. + +## Pitfalls +- Frequent modifications (high churn) suggest instability; avoid over-reliance on fragile tests. +- Be cautious with mocking: over-mocking can hide integration issues. +- Watch for tests that depend on timing or order, which can cause flakiness. +- Avoid testing implementation details; focus on behavior. +- Beware of tests that are too broad or too narrow, reducing maintainability. +- Frequent updates in `server.test.ts` indicate areas prone to breakage; review for brittle assertions or tightly coupled tests. + +## Dependencies +- **Testing Framework:** Ensure consistent use of Jest (or the relevant framework) APIs. +- **Mocking Libraries:** Use dedicated mocking tools (e.g., jest.mock) to isolate external modules. +- **Environment Variables:** Use test-specific environment configs to prevent interference with production settings. +- **Internal Modules:** When extending tests, import only the necessary modules; avoid deep coupling. +- **CI/CD Integration:** Confirm tests are compatible with CI pipelines, considering frequent churn hotspots. + +--- + +**Note:** Given the high modification frequency, prioritize stabilizing tests, avoiding brittle assertions, and documenting assumptions explicitly to aid future maintenance. \ No newline at end of file diff --git a/packages/app/server/src/__tests__/AGENTS_this_test_module_f0f826d2.md b/packages/app/server/src/__tests__/AGENTS_this_test_module_f0f826d2.md new file mode 100644 index 000000000..1ab03ac96 --- /dev/null +++ b/packages/app/server/src/__tests__/AGENTS_this_test_module_f0f826d2.md @@ -0,0 +1,50 @@ +# Responses Test Module (packages/app/server/src/__tests__/responses.test.ts) + +## Purpose +This test module verifies the correctness of response handling logic, ensuring that response objects conform to expected structures and behaviors. It primarily tests the interaction with the Key module and the OpenAI API integration. + +## Boundaries +- **Belongs here:** Tests for response data structures, response-related utility functions, and API interaction mocks. +- **Does NOT belong:** Implementation of core response generation logic, business rules outside response formatting, or modules outside the `__tests__` directory. Tests should not include actual API calls; all external interactions must be mocked. + +## Invariants +- Test setup (`beforeAll`) must initialize all necessary mocks and environment variables before any test runs. +- Response objects returned by the system must include all required fields with correct types. +- Mocked OpenAI responses must be consistent with expected API schemas. +- Test execution order is not guaranteed; tests should be independent and idempotent. +- No real API calls are made; all external dependencies are mocked to prevent side effects and flakiness. +- The Key module's calls (likely functions or classes) must be invoked exactly as expected, respecting any sequence or parameter contracts. + +## Patterns +- Use `describe` blocks to group related response tests logically. +- Use `test` blocks with explicit, descriptive names indicating the specific response scenario. +- Mock external dependencies (`OpenAI`, `Key`) at the start of each test or in `beforeAll`. +- Follow naming conventions: test descriptions should specify input conditions and expected outcomes. +- Validate response objects with `expect` assertions on structure, content, and types. +- Handle asynchronous code with `async/await` consistently. +- Maintain clear separation between setup, execution, and verification phases. + +## Pitfalls +- Failing to mock external API calls (`OpenAI`) leads to flaky tests and unintended side effects. +- Relying on mutable shared state across tests causes test pollution; always reset mocks/state. +- Modifying `responses.test.ts` frequently (5 versions) indicates high churn; avoid over-specification or brittle assertions. +- Ignoring the dependency on `Key` can cause tests to pass incorrectly if the dependency's contract changes. +- Overlooking the importance of null-safety and type assertions can hide bugs. +- Be cautious with test order dependencies; do not assume tests run sequentially. +- Changes in the response structure or API schema require updating both the code and tests simultaneously. + +## Dependencies +- **OpenAI:** Used for generating or validating responses; ensure correct API schema usage and mock responses accordingly. +- **beforeAll:** Sets up global test environment, mocks, and environment variables; verify it covers all necessary initializations. +- **describe:** Organizes tests; maintain logical grouping for clarity. +- **expect:** Used for assertions; ensure assertions are comprehensive, covering structure, content, and types. +- **test:** Defines individual test cases; write descriptive names and handle async code properly. + +--- + +**Additional Notes for Agents:** +- Focus on the dependency on the `Key` module; understand how it is called and what responses or side effects it produces. +- Recognize that the test file is a high-churn hotspot; frequent updates may reflect evolving response schemas or testing strategies. +- Be aware that no child intent nodes exist; this is a leaf node, so modifications should be localized. +- Pay attention to the external dependencies' correct usage to prevent false positives/negatives in tests. +- Remember that external API interactions are mocked; verify mocks are accurate and reflect real API behavior for reliable tests. \ No newline at end of file diff --git a/packages/app/server/src/__tests__/AGENTS_this_test_suite_c3b76fee.md b/packages/app/server/src/__tests__/AGENTS_this_test_suite_c3b76fee.md new file mode 100644 index 000000000..430bbc7d5 --- /dev/null +++ b/packages/app/server/src/__tests__/AGENTS_this_test_suite_c3b76fee.md @@ -0,0 +1,47 @@ +# Endpoints Test Suite (packages/app/server/src/__tests__/endpoints.test.ts) + +## Purpose +This test suite verifies the correctness of API endpoints in the server, ensuring they handle requests and responses as expected. It primarily tests integration points, focusing on endpoint behavior under various conditions. + +## Boundaries +- **Belongs here:** Tests for all API endpoint routes defined within the server, including request validation, response structure, and error handling. +- **Does NOT belong:** Business logic implementations, database interactions, or middleware code; these should be tested separately in unit or integration tests outside this file. + +## Invariants +- Tests assume a consistent environment setup via `beforeAll` and `afterAll`; these hooks must initialize and clean up resources properly. +- No test should depend on the order of execution; tests must be independent and idempotent. +- External dependencies (e.g., network calls, databases) should be mocked or stubbed unless explicitly testing integration. +- Response assertions must verify status codes, headers, and payloads match expected schemas. +- Test data should be isolated; avoid shared mutable state across tests to prevent flaky results. +- The test suite must not modify production data or configurations. + +## Patterns +- Use `beforeAll` to set up global test context (e.g., starting server, initializing mocks). +- Use `afterAll` for cleanup (e.g., shutting down server, resetting mocks). +- Name test cases clearly to reflect endpoint, method, and condition (e.g., "GET /users returns 200 with user list"). +- Follow consistent request/response validation patterns, using helper functions if available. +- Handle asynchronous operations with `async/await`; avoid callback hell. +- Use descriptive error messages in assertions to facilitate debugging. +- Maintain clear separation between setup, execution, and verification phases within each test. + +## Pitfalls +- Over-reliance on real external services; can cause flaky tests and slow runs. +- Forgetting to reset mocks/stubs in `afterAll` or between tests, leading to state leakage. +- Assuming order-dependent tests; always ensure tests are independent. +- Modifying shared test data or global state during tests, risking side effects. +- Ignoring high-churn test cases; frequent modifications may introduce instability. +- Not validating all response aspects (status, headers, body), risking incomplete coverage. +- Failing to handle asynchronous errors properly, leading to unhandled promise rejections. +- Overlooking edge cases such as invalid inputs, missing headers, or boundary conditions. + +## Dependencies +- **`afterAll` / `beforeAll`**: Used for setup and teardown; ensure they correctly initialize and clean test environment. +- External mocks/stubs should be configured within these hooks to prevent leakage. +- Use mocking libraries (e.g., Jest mocks) carefully to simulate external systems; verify mocks are reset after tests. +- Avoid external network calls; rely on controlled, predictable mock responses. +- Ensure environment variables or configuration files required for tests are correctly loaded and do not interfere with production settings. +- Be aware of test runtime dependencies, such as local servers or databases, and document their setup requirements. + +--- + +**Note:** This test suite is a high-churn hotspot; expect frequent updates. Maintain strict discipline in test isolation, mocking, and cleanup to prevent flakiness. \ No newline at end of file diff --git a/packages/app/server/src/clients/AGENTS_encapsulates_logic_bacebfc1.md b/packages/app/server/src/clients/AGENTS_encapsulates_logic_bacebfc1.md new file mode 100644 index 000000000..d218089dd --- /dev/null +++ b/packages/app/server/src/clients/AGENTS_encapsulates_logic_bacebfc1.md @@ -0,0 +1,53 @@ +# Packages/app/server/src/clients + +## Purpose +Encapsulates client-side logic for interacting with external AI models via the OpenRouter API, providing request handling, model selection, and streaming support to facilitate server communication with AI services. + +## Boundaries +- **Belongs:** + - `makeRequest`: core request logic, including streaming control and request configuration + - `getRandomModel`: logic for selecting a default or random model + - `openrouter-client.ts`: configuration, API endpoints, and client setup specific to OpenRouter API +- **Does NOT belong:** + - Business logic unrelated to API communication (e.g., user management, UI handling) + - Internal server logic outside client API calls (e.g., database operations, auth) + - External integrations beyond OpenAI/OpenRouter (e.g., other AI providers) + +## Invariants +- `makeRequest` must always handle errors gracefully, ensuring no unhandled promise rejections or silent failures. +- When `useStreaming` is true, `makeRequest` must correctly process and forward streamed data chunks; when false, it should handle complete responses. +- `getRandomModel` must return a valid, supported model string; invalid models should be avoided or fallback mechanisms used. +- The module `packages/app/server/src/clients/openrouter-client.ts` must be initialized with correct API credentials and endpoint URLs before use. +- No assumptions about the response structure should be made outside documented API contracts; validation is required. + +## Patterns +- Use explicit default parameters (`useStreaming = false`) in `makeRequest`. +- Follow consistent naming conventions: `makeRequest`, `getRandomModel`, and the module name. +- Handle errors with try-catch blocks; propagate errors with meaningful messages. +- When modifying `makeRequest`, ensure that streaming and non-streaming modes are mutually exclusive and correctly managed. +- Use `getRandomModel` to select models from a predefined list or API-supported models, avoiding hardcoded unsupported models. +- Maintain idempotency in `getRandomModel`—return consistent results unless underlying model list changes. +- Document assumptions about external dependencies (e.g., OpenAI) and ensure correct import/use patterns. + +## Pitfalls +- Frequent modifications to `makeRequest` increase risk of inconsistent request configurations or streaming mishandling. +- Hardcoding model names in `getRandomModel` can lead to unsupported models; prefer dynamic retrieval if possible. +- Forgetting to handle streaming data correctly in `makeRequest` can cause data loss or incomplete responses. +- Not validating API credentials or endpoint URLs in `openrouter-client.ts` may cause runtime failures. +- Overlooking error propagation or mismanaging exceptions can lead to unhandled promise rejections. +- Changes in external dependencies (OpenAI) API or SDK may require updates in request handling logic. + +## Dependencies +- **OpenAI SDK:** + - Use according to official documentation. Ensure API keys are securely stored and correctly injected. + - Validate API response schemas before processing. +- **Configuration:** + - Confirm API endpoint URLs and credentials are correctly set in `openrouter-client.ts`. +- **Model support:** + - `getRandomModel` relies on supported models; keep this list updated with available models from OpenRouter/OpenAI. +- **Error handling:** + - Implement robust try-catch blocks around API calls to handle network issues, rate limits, or invalid responses. +- **Streaming support:** + - When `useStreaming` is true, ensure the client properly subscribes to data streams and handles partial data. +- **Churn awareness:** + - Be cautious with frequent modifications to core functions; document changes thoroughly to prevent regressions. \ No newline at end of file diff --git a/packages/app/server/src/clients/AGENTS_this_module_provides_218d0309.md b/packages/app/server/src/clients/AGENTS_this_module_provides_218d0309.md new file mode 100644 index 000000000..a44fb2f26 --- /dev/null +++ b/packages/app/server/src/clients/AGENTS_this_module_provides_218d0309.md @@ -0,0 +1,53 @@ +# Packages/app/server/src/clients + +## Purpose +This module provides functions to create and send image editing requests to the OpenAI API, supporting both single and multiple image inputs, and manages the construction of form data for these requests. + +## Boundaries +- **Belongs here:** + - Construction of multipart/form-data payloads for image editing requests. + - Handling of image file inputs and conversion to suitable formats. + - Interaction with OpenAI's image editing endpoints. +- **Does NOT belong here:** + - Core image processing or manipulation logic (handled elsewhere). + - API key management or authentication (should be configured externally). + - Business logic related to user workflows or UI interactions. + - Storage or retrieval of images outside the request payload. + +## Invariants +- The `makeImageEditRequest` and `makeImageEditRequestWithMultipleImages` functions must always produce a valid form data payload compatible with OpenAI's API. +- Image files passed to these functions must be valid, readable, and correctly formatted; invalid files should trigger errors. +- When multiple images are provided, their order must be preserved in the form data. +- Null or undefined image inputs are not permitted; all image parameters must be validated before request construction. +- The functions should handle errors gracefully, ensuring form data is not sent if invalid. +- The module must not depend on any stateful or mutable external variables; all data should be passed explicitly. +- Resource management: Files should be properly handled, ensuring no leaks or dangling file handles. + +## Patterns +- Use explicit, descriptive naming for form data fields consistent with OpenAI API expectations. +- Validate all image inputs before constructing form data; reject invalid or missing images. +- For multiple images, iterate over the array, appending each with a unique key (e.g., `images[0]`, `images[1]`) if required. +- Handle errors with clear exceptions; do not swallow API or file errors silently. +- Maintain consistent async/await patterns; ensure all file operations are awaited. +- Use `toFile()` for image file conversion, ensuring the output is compatible with form data. +- Follow the existing code style for function signatures, including parameter naming and return types. + +## Pitfalls +- Forgetting to validate image files can lead to API errors or malformed requests. +- Not preserving image order in multiple-image requests may cause unexpected edits. +- Churning on the request functions (noted as frequently modified) risks introducing bugs; ensure thorough validation. +- Mismanaging file handles—failing to close or properly handle files—can cause resource leaks. +- Assuming all images are in the same format; conversion issues may arise if images are incompatible. +- Not updating form data keys to match API expectations when API evolves. +- Overlooking error handling in async functions can cause unhandled promise rejections. +- Ignoring the need for consistent naming conventions for form data fields may cause API rejection. + +## Dependencies +- **OpenAI:** Use the official OpenAI SDK or API client to send requests; ensure API keys and configurations are correctly set. +- **file:** Handle file input/output operations; validate and process image files reliably. +- **images:** For image manipulation or validation if needed; ensure compatibility with form data. +- **toFile:** Convert image objects or buffers into file streams suitable for form data payloads; handle conversion errors explicitly. + +--- + +**Note:** When modifying this module, ensure compliance with OpenAI API specifications, validate all inputs rigorously, and maintain the integrity of form data construction to prevent request failures. \ No newline at end of file diff --git a/packages/app/server/src/middleware/AGENTS.md b/packages/app/server/src/middleware/AGENTS.md new file mode 100644 index 000000000..0ad72c60a --- /dev/null +++ b/packages/app/server/src/middleware/AGENTS.md @@ -0,0 +1,44 @@ +# Transaction Escrow Middleware + +## Purpose +Encapsulates logic for managing transaction escrow processes within the server middleware layer, ensuring secure, consistent handling of transaction states and related operations during request processing. + +## Boundaries +- **Belongs:** Middleware functions that intercept and process HTTP requests related to transaction escrow; core logic for escrow state transitions. +- **Does NOT belong:** Business logic outside request lifecycle (e.g., domain models, service layer); database access code; external API integrations unrelated to middleware; configuration setup. + +## Invariants +- Middleware must always validate the presence and correctness of transaction identifiers before proceeding. +- Escrow state transitions must follow a strict finite state machine; invalid transitions must be rejected. +- Request processing should not mutate escrow state unless explicitly authorized and validated. +- Null or undefined transaction data should abort processing early. +- Middleware must not leak sensitive transaction data in logs or error responses. +- Resource cleanup (e.g., releasing locks or escrow holds) must occur reliably on request completion or error. + +## Patterns +- Use consistent naming conventions: functions prefixed with `handle`, `validate`, or `transition`. +- Error handling should be explicit; throw or propagate errors with clear, descriptive messages. +- Middleware functions should be idempotent; repeated calls with same input should not cause inconsistent state. +- Validate transaction IDs and escrow data early; avoid side effects if validation fails. +- Follow the existing pattern of short-circuiting on validation failures. +- Use explicit state transition functions that enforce allowed state changes. +- Maintain clear separation between validation logic and state mutation. + +## Pitfalls +- **Churn Hotspot:** Frequent modifications to `transaction-escrow-middleware.ts` suggest instability; avoid making ad-hoc changes without understanding existing patterns. +- **State Violations:** Transitioning escrow states out of order or skipping states can corrupt transaction flow. +- **Null Safety:** Failing to check for null/undefined transaction data can cause runtime errors. +- **Concurrency:** Middleware may be invoked concurrently; ensure idempotency and avoid race conditions. +- **Logging:** Over-logging sensitive data may leak information; log only non-sensitive identifiers and statuses. +- **Error Handling:** Not catching or properly propagating errors can leave transactions in inconsistent states. +- **Churn Risks:** Frequent updates imply potential instability; test thoroughly before deploying changes. + +## Dependencies +- **External:** None explicitly imported; relies on internal modules for transaction state management. +- **Usage:** Ensure any external utility functions or constants used for validation or state transitions are imported and used consistently. +- **Versioning:** Be aware of the high-churn status; verify compatibility with current codebase version before making modifications. +- **Testing:** Rely on existing test coverage for middleware; extend tests for new state transition paths or validation rules. + +--- + +*Note:* This node assumes familiarity with the escrow state machine, middleware request lifecycle, and transaction validation patterns within the codebase. Always verify that modifications preserve invariants and follow established patterns. \ No newline at end of file diff --git a/packages/app/server/src/providers/AGENTS_defines_a_centralize_50e18a09.md b/packages/app/server/src/providers/AGENTS_defines_a_centralize_50e18a09.md new file mode 100644 index 000000000..fad69c012 --- /dev/null +++ b/packages/app/server/src/providers/AGENTS_defines_a_centralize_50e18a09.md @@ -0,0 +1,50 @@ +# ProviderFactory.ts Intent Node + +## Purpose +Defines a centralized factory for mapping AI models to their respective providers, enabling dynamic provider selection based on model type for chat, image, and video AI models. It abstracts provider instantiation logic, facilitating extensibility and consistency across media types. + +## Boundaries +- **Belongs:** Creation functions `createChatModelToProviderMapping`, `createImageModelToProviderMapping`, `createVideoModelToProviderMapping`; provider registration logic; model-to-provider mapping logic. +- **Does NOT belong:** Actual provider implementations; model definitions; external API integrations; UI or client-facing code; unrelated configuration or environment setup. + +## Invariants +- The functions `createChatModelToProviderMapping`, `createImageModelToProviderMapping`, `createVideoModelToProviderMapping` must return valid, non-null mappings. +- Mappings should be immutable after creation; no runtime modifications. +- Provider instances must be correctly associated with their respective models; mismatches can cause runtime errors. +- The factory should handle unknown models gracefully, either by defaulting or throwing explicit errors. +- Null-safety: All model keys and provider values in mappings must be non-null. +- Ordering of entries in mappings is not guaranteed; rely on explicit keys rather than positional assumptions. +- No side effects or external state mutations during mapping creation. + +## Patterns +- Use dedicated creation functions (`createChatModelToProviderMapping`, etc.) for each media type. +- Maintain naming conventions: functions prefixed with `create` and ending with `Mapping`. +- Encapsulate provider instantiation within these functions; avoid direct provider creation outside. +- Handle unknown or unsupported models explicitly, e.g., throw errors or fallback to defaults. +- Prefer immutable objects for mappings; avoid mutability after creation. +- Document expected model keys and provider types for each mapping. +- Use consistent error handling: throw descriptive errors on misconfigurations. +- Avoid circular dependencies; this module should not depend on provider implementations directly. + +## Pitfalls +- Churn: Frequent modifications to `ProviderFactory.ts` suggest evolving model-provider mappings; ensure changes are well-tested. +- Misalignment: Incorrect model keys or provider associations can cause runtime failures. +- Overly dynamic mappings: Avoid runtime modifications; prefer static, predictable mappings. +- Forgetting to update all three creation functions when adding new models or providers. +- Implicit assumptions about model types or provider capabilities; validate mappings explicitly. +- Dependency on external modules (`createChatModelToProviderMapping`, etc.) must be correct; misconfigurations here can break the entire factory. +- Null or undefined values in mappings can cause runtime errors; enforce non-null constraints. +- High churn indicates the need for comprehensive tests covering all model-provider combinations. + +## Dependencies +- External functions: `createChatModelToProviderMapping`, `createImageModelToProviderMapping`, `createVideoModelToProviderMapping`. +- These functions must be correctly implemented to produce valid, complete mappings. +- Ensure these functions are imported correctly and are up-to-date with supported models and providers. +- No direct dependencies on provider implementations; only on the mapping creation functions. +- External models and providers should be validated against the mappings to prevent mismatches. +- Be cautious of version mismatches; frequent updates imply the need for regression testing. + +--- + +**Summary:** +This node encapsulates the logic for dynamically mapping media models to providers, serving as a critical abstraction layer. Agents must understand the creation patterns, invariants, and potential pitfalls—especially churn and dependency correctness—to maintain robustness and extensibility. \ No newline at end of file diff --git a/packages/app/server/src/providers/AGENTS_encapsulates_integra_b402fe6d.md b/packages/app/server/src/providers/AGENTS_encapsulates_integra_b402fe6d.md new file mode 100644 index 000000000..a58542869 --- /dev/null +++ b/packages/app/server/src/providers/AGENTS_encapsulates_integra_b402fe6d.md @@ -0,0 +1,43 @@ +# GeminiVeoProvider.ts + +## Purpose +Encapsulates integration logic with the GeminiVeo external service, managing API interactions, request handling, and response parsing. It acts as the primary interface for consuming GeminiVeo data within the server. + +## Boundaries +- **Belongs to:** Provider layer responsible for external service integrations. +- **Does NOT belong to:** Business logic, data persistence, or UI layers. +- **External APIs:** Assumes stable API endpoints and response schemas; any schema change requires code updates. +- **Configuration:** Sensitive parameters (API keys, endpoints) should be injected via environment variables or configuration files, not hardcoded. +- **Error Handling:** Should gracefully handle network errors, timeouts, and unexpected responses; do not propagate raw errors upstream. + +## Invariants +- **Request Idempotency:** Requests to GeminiVeo API must include proper authentication tokens and adhere to rate limits. +- **Response Validation:** All responses must be validated against expected schemas; invalid responses should trigger fallback/error logic. +- **Null Safety:** Null or undefined responses from the API should be handled explicitly; do not assume presence of data. +- **Resource Management:** Persistent connections or retries should be managed to avoid leaks or excessive load. +- **Versioning:** The module is version-sensitive; modifications should consider backward compatibility if multiple versions are in use. + +## Patterns +- **Naming:** Use clear, descriptive method names reflecting GeminiVeo API actions (e.g., `fetchVeoData`, `parseResponse`). +- **Error Handling:** Use try-catch blocks around async API calls; log errors with context. +- **Configuration:** Use environment variables for API URLs, tokens; validate their presence at startup. +- **Response Parsing:** Centralize response validation and parsing logic; avoid duplicated code. +- **Churn Management:** Given high modification frequency, document assumptions and API contract expectations explicitly in code comments. + +## Pitfalls +- **Frequent Changes:** The module is highly volatile; avoid hardcoded values, and implement robust version checks. +- **Coupling:** Tight coupling to specific API response schemas can cause fragility; abstract response handling where possible. +- **Churn Risks:** Frequent updates increase risk of regressions; implement comprehensive tests around API interactions. +- **Null/Undefined Responses:** Failing to check for missing data can cause runtime errors. +- **Rate Limits & Retries:** Ignoring API rate limits or retry strategies can lead to throttling or data inconsistency. +- **Configuration Errors:** Missing or incorrect environment variables can cause silent failures; validate at startup. + +## Dependencies +- **HTTP Client:** Use the designated HTTP library (e.g., axios, fetch) with proper timeout settings. +- **Logging:** Integrate with the application's logging system to record request/response details and errors. +- **Configuration Management:** Rely on environment variables or configuration files for API URLs and tokens; validate their presence early. +- **Error Monitoring:** Ensure integration with error tracking tools if available, to catch and analyze failures rapidly. + +--- + +**Note:** Due to high churn, document assumptions explicitly, and consider adding version checks or feature flags to manage API schema evolution safely. \ No newline at end of file diff --git a/packages/app/server/src/providers/AGENTS_encapsulates_interac_7d70c810.md b/packages/app/server/src/providers/AGENTS_encapsulates_interac_7d70c810.md new file mode 100644 index 000000000..4974c76c3 --- /dev/null +++ b/packages/app/server/src/providers/AGENTS_encapsulates_interac_7d70c810.md @@ -0,0 +1,43 @@ +# VertexAIProvider.ts + +## Purpose +Encapsulates interactions with Google Cloud Vertex AI, providing methods for model invocation, batch processing, and resource management. It abstracts API calls, handles authentication, and manages request configurations specific to Vertex AI services. + +## Boundaries +- **Belongs here:** All logic related to Vertex AI API calls, including request construction, response parsing, and error handling. +- **Does NOT belong here:** General cloud infrastructure setup, authentication setup outside Vertex AI context, or unrelated API integrations (e.g., other Google Cloud services or external APIs). Utility functions unrelated to Vertex AI should reside elsewhere. + +## Invariants +- API requests must include valid authentication tokens; token refresh logic is handled internally. +- All API calls must conform to the expected request schema; invalid requests should trigger retries or specific error handling. +- Responses are assumed to contain expected data structures; null or malformed responses should be gracefully handled. +- Resource cleanup (e.g., closing streams or cancelling requests) must be performed to prevent leaks. +- Request parameters (model names, endpoints, configuration options) are immutable during a single invocation cycle. +- Churn is high; frequent modifications suggest evolving API endpoints or internal request schemas, so agents should verify current API versions before modifications. + +## Patterns +- Use consistent naming conventions: methods prefixed with `get`, `create`, `update`, `delete` as appropriate. +- Handle errors explicitly; do not swallow exceptions silently. +- Use async/await for all API interactions; ensure proper error propagation. +- Maintain clear separation between request construction and response handling. +- Use configuration objects for request parameters; avoid hardcoded values. +- Follow the existing code structure for API client initialization, including token management. +- Log relevant request/response metadata for debugging, especially in error scenarios. + +## Pitfalls +- **Churn risk:** Frequent updates to API endpoints or request schemas; agents must verify current API specs before modifications. +- **Null safety:** Responses may be incomplete or null; always validate response data before use. +- **Authentication:** Token refresh logic is critical; failure to handle token expiration leads to failed requests. +- **Concurrency:** Multiple simultaneous requests may cause race conditions; ensure request idempotency and proper error handling. +- **Resource leaks:** Not closing streams or cancelling requests can cause memory leaks; always clean up. +- **Configuration drift:** Hardcoded values or outdated API versions can cause failures; keep configuration centralized and up-to-date. + +## Dependencies +- **Google Cloud SDK / Vertex AI API client libraries:** Use official SDKs for request signing, endpoint management, and response parsing. +- **Authentication modules:** Ensure secure token management, possibly via environment variables or secret managers. +- **Logging utilities:** For debugging and tracing request flows, especially under high churn. +- **Configuration management:** Centralized configs for API endpoints, model names, and request options to facilitate updates and consistency. + +--- + +*Note:* Given the high churn and frequent modifications, agents should implement robust version checks and validation steps before deploying changes. Regularly review API documentation for updates to request schemas and endpoint URLs. \ No newline at end of file diff --git a/packages/app/server/src/providers/AGENTS_encapsulates_interac_92ce70a0.md b/packages/app/server/src/providers/AGENTS_encapsulates_interac_92ce70a0.md new file mode 100644 index 000000000..e2628af50 --- /dev/null +++ b/packages/app/server/src/providers/AGENTS_encapsulates_interac_92ce70a0.md @@ -0,0 +1,47 @@ +# OpenAIImageProvider Module + +## Purpose +Encapsulates interaction logic with OpenAI's image generation API, providing a streamlined interface for generating images based on prompts within the server environment. It manages API requests, handles responses, and abstracts OpenAI-specific details from higher-level application code. + +## Boundaries +- **Belongs here:** All code related to constructing API requests, handling responses, error management specific to OpenAI's image API, and configuration of API keys or endpoints. +- **Does NOT belong here:** Image processing unrelated to OpenAI API (e.g., local image manipulation), UI rendering, or client-side logic. Business logic that orchestrates multiple providers should reside outside this module. + +## Invariants +- API key configuration must be securely managed and never hardcoded. +- Requests to OpenAI must include valid parameters; invalid parameters should trigger predictable error handling. +- Responses must be validated for expected structure before use; null or malformed responses must be gracefully handled. +- The module should not assume success; always handle potential API failures or rate limits. +- Resource cleanup (e.g., closing HTTP connections) must be guaranteed if applicable. +- The module's methods should be idempotent where applicable, avoiding side effects on repeated calls with the same inputs. + +## Patterns +- Use consistent naming conventions: e.g., `generateImage(prompt: string): Promise`. +- Error handling should follow a try-catch pattern, with errors propagated or logged explicitly. +- API request construction should be parameterized, allowing easy updates to request parameters. +- Use environment variables or configuration files for API keys and endpoints. +- Responses should be parsed and validated against expected schemas before use. +- Incorporate retry logic for transient errors, respecting rate limits. +- Document expected input/output formats clearly. + +## Pitfalls +- Frequent modifications (5 versions) indicate high churn; avoid making breaking changes without thorough testing. +- Mismanaging API keys or endpoints can lead to security issues or failed requests. +- Ignoring rate limits may cause request failures; implement backoff strategies. +- Failing to validate API responses can lead to runtime errors downstream. +- Hardcoding configuration values reduces flexibility; always externalize. +- Overlooking error handling can cause unhandled promise rejections or crashes. +- Coupling tightly to specific API versions without abstraction hampers future updates. + +## Dependencies +- **OpenAI API Client:** Use the official or well-maintained SDK for request consistency. +- **Configuration Management:** Environment variables or config files for API keys (`OPENAI_API_KEY`) and endpoints. +- **Logging:** Implement structured logging for request/response cycles and errors. +- **Error Handling Utilities:** Use or develop utilities for retries, exponential backoff, and error categorization. +- **Type Definitions:** Maintain accurate TypeScript interfaces for request payloads and response schemas to ensure type safety. +- **Testing Framework:** Mock API responses to test request handling, error scenarios, and response validation. + +--- + +**Actionable Summary:** +Ensure API keys are securely managed, validate all responses, handle errors and rate limits explicitly, and avoid making breaking changes without comprehensive testing. Follow consistent naming and request patterns, externalize configuration, and incorporate retries for transient failures. \ No newline at end of file diff --git a/packages/app/server/src/providers/AGENTS_encapsulates_logic_f_901f9cb0.md b/packages/app/server/src/providers/AGENTS_encapsulates_logic_f_901f9cb0.md new file mode 100644 index 000000000..7a380ec63 --- /dev/null +++ b/packages/app/server/src/providers/AGENTS_encapsulates_logic_f_901f9cb0.md @@ -0,0 +1,48 @@ +# OpenAIVideoProvider Module + +## Purpose +Encapsulates logic for interfacing with OpenAI's video-related APIs, managing video generation, processing, and related configurations within the server environment. Acts as the primary abstraction layer for video services relying on OpenAI. + +## Boundaries +- **Belongs:** All video processing, API calls, and configuration specific to OpenAI's video services. +- **Does NOT belong:** General API utilities, unrelated provider integrations, or UI-layer code. Business logic unrelated to video processing should be elsewhere. + +## Invariants +- Maintain consistent API key and endpoint configurations; do not override or bypass environment-based settings. +- Ensure all API requests include necessary authentication headers; null or missing tokens cause failures. +- Video request parameters (e.g., resolution, format) must adhere to OpenAI's supported options; invalid parameters should trigger explicit errors. +- Resource cleanup: ensure any streams or temporary files are properly closed/deleted after processing. +- Versioning: the module is frequently updated; avoid assumptions about internal structure stability; rely on public interfaces and documented behaviors. +- Null-safety: handle potential null responses from API calls gracefully, with explicit error handling. + +## Patterns +- Use explicit async/await patterns for all API interactions. +- Follow consistent naming conventions: e.g., `generateVideo`, `fetchVideoStatus`. +- Error handling: catch API errors, log detailed context, and propagate meaningful exceptions. +- Configuration: load API keys and endpoints from environment variables or configuration files during initialization. +- Request payloads: construct with strict validation; avoid sending unsupported parameters. +- Retry logic: implement idempotent retries for transient failures, respecting rate limits. +- Logging: include contextual info (request IDs, timestamps) for traceability. +- Version control: document and lock dependencies related to OpenAI SDKs or HTTP clients. + +## Pitfalls +- Churn hotspots: frequent modifications suggest instability; avoid making assumptions about internal implementation. +- API rate limits: unhandled retries or excessive requests can cause throttling. +- Null responses or unexpected API errors: can cause runtime exceptions if not properly checked. +- Misconfigured API keys or endpoints: silently fail or produce invalid responses. +- Ignoring API version updates: may break compatibility; monitor OpenAI API changelogs. +- Overlooking resource cleanup: temporary files or streams may leak if not properly managed. +- Hardcoded parameters: avoid; rely on configurable options to prevent bugs when API specs change. +- Lack of detailed error handling: can obscure root causes during failures. + +## Dependencies +- **OpenAI API SDK or HTTP client:** Use the official SDK or a well-maintained HTTP library; ensure compatibility with current API versions. +- **Configuration management:** Load API keys and endpoints from environment variables or secure config files; validate presence at startup. +- **Logging framework:** Use consistent logging for request/response tracking, especially for error conditions. +- **Error handling utilities:** Implement or leverage existing patterns for retrying transient errors and handling API failures. +- **Type definitions:** Strictly type API request/response schemas to prevent runtime errors. +- **Version control:** Track dependencies' versions to prevent incompatibilities; update cautiously alongside API changes. + +--- + +**Note:** Given the high churn rate, agents should treat this module as volatile; verify assumptions against current code and API documentation before making modifications. \ No newline at end of file diff --git a/packages/app/server/src/providers/AGENTS_encapsulates_the_int_612d603b.md b/packages/app/server/src/providers/AGENTS_encapsulates_the_int_612d603b.md new file mode 100644 index 000000000..ab37445ec --- /dev/null +++ b/packages/app/server/src/providers/AGENTS_encapsulates_the_int_612d603b.md @@ -0,0 +1,45 @@ +# AnthropicNativeProvider.ts + +## Purpose +Encapsulates the integration with Anthropic's native API, managing prompt submission, response retrieval, and token handling. It provides a specialized interface for interacting with Anthropic models within the server environment, abstracting API details and ensuring consistent request/response handling. + +## Boundaries +- **Belongs here:** All logic related to constructing requests, managing API keys, handling responses, and token counting for Anthropic models. +- **Does NOT belong here:** Any logic related to other LLM providers, general request routing, or application-specific business logic unrelated to Anthropic API interactions. Utility functions or shared helpers should reside elsewhere. + +## Invariants +- API keys must be securely stored and retrieved; never hardcoded. +- Requests must include required parameters (e.g., model name, prompt, temperature). +- Responses must be validated for expected structure; handle errors gracefully. +- Token counting must be accurate; avoid exceeding model token limits. +- The provider must handle rate limits and retries according to Anthropic's API specifications. +- Null or undefined responses from the API should trigger explicit error handling. +- Churn-prone: Be cautious when modifying request/response schemas; ensure backward compatibility. + +## Patterns +- Use consistent naming conventions: e.g., `sendPrompt()`, `parseResponse()`. +- Error handling should follow the pattern of catching exceptions, logging, and propagating meaningful errors. +- API interactions should be asynchronous, returning Promises. +- Token counting should leverage existing utilities, ensuring consistency. +- Configuration (e.g., API URL, timeout) should be centralized and environment-driven. +- Maintain clear separation between request construction, response parsing, and error handling. + +## Pitfalls +- Frequent modifications increase risk of breaking token limits or request formats. +- Hardcoding API keys or sensitive data introduces security risks. +- Ignoring rate limits can cause request failures or bans. +- Mismanaging null/undefined responses leads to runtime errors. +- Changes in the Anthropic API (e.g., endpoint updates, parameter changes) require careful version tracking. +- Overlooking token counting inaccuracies may cause prompt truncation or API errors. +- Be vigilant about concurrency issues if multiple requests are handled simultaneously. + +## Dependencies +- Token counting utilities: Ensure they are accurate and compatible with Anthropic models. +- Environment variables/configuration management: For API keys and endpoints. +- Logging framework: For error reporting and debugging. +- Error handling utilities: To standardize API error responses. +- (Optional) Retry logic libraries: To handle transient API failures gracefully. + +--- + +**Note:** Given the high churn rate, maintain thorough version control and document API schema changes. Regularly review external API documentation for updates affecting request/response formats. \ No newline at end of file diff --git a/packages/app/server/src/providers/AGENTS_the_module_c0069ef3.md b/packages/app/server/src/providers/AGENTS_the_module_c0069ef3.md new file mode 100644 index 000000000..0b37eeea8 --- /dev/null +++ b/packages/app/server/src/providers/AGENTS_the_module_c0069ef3.md @@ -0,0 +1,45 @@ +# GeminiProvider Module + +## Purpose +The GeminiProvider.ts module encapsulates logic for interfacing with the Gemini API, managing authentication, request formation, and response handling. It acts as the core abstraction layer for Gemini integrations within the server, enabling other components to interact with Gemini services without direct API calls. + +## Boundaries +- **Belongs here:** All Gemini API interactions, including request construction, response parsing, error handling, and authentication management. +- **Does NOT belong here:** Business logic unrelated to Gemini API communication (e.g., UI concerns, unrelated data processing). Utility functions or shared helpers should reside in dedicated utility modules, not within GeminiProvider. + +## Invariants +- Authentication tokens or credentials are always valid before making requests; refresh or re-authenticate as needed. +- Requests to Gemini API must include necessary headers, such as API keys or OAuth tokens, consistently. +- Responses are assumed to be in a specific format; any deviation should trigger error handling. +- The module must handle rate limiting or throttling signals from Gemini API gracefully, implementing retries or backoff strategies. +- Null-safety: Return values from API calls should never be null; errors must be propagated explicitly. +- Resource management: Persistent connections (if any) are properly closed or reused; no dangling network resources. + +## Patterns +- Use consistent naming conventions: methods prefixed with `fetch`, `send`, or `build`. +- Error handling follows a pattern: catch exceptions, log detailed context, and propagate or convert to domain-specific errors. +- API request formation should utilize a dedicated request builder pattern, ensuring headers, payloads, and endpoints are correctly assembled. +- Asynchronous operations should use `async/await` with try-catch blocks; avoid unhandled promise rejections. +- Sensitive data (API keys, tokens) must be stored securely, not hardcoded; use environment variables or secure vaults. +- When modifying, adhere to existing code style and ensure backward compatibility with current API interaction patterns. + +## Pitfalls +- Frequent modifications (5 versions) indicate high churn; avoid introducing unstable changes without thorough testing. +- Risk of breaking authentication flow; ensure token refresh logic is robust and tested. +- Potential for inconsistent request headers or payloads, leading to API errors. +- Overlooking rate limiting responses can cause request throttling or bans. +- Null or undefined responses from Gemini API are not handled gracefully; always validate responses. +- Coupling tightly to specific API response formats without abstraction can hinder future API version upgrades. +- Mismanagement of asynchronous flows can cause race conditions or unhandled errors. +- Hardcoded credentials or environment variables may lead to security issues or deployment failures. + +## Dependencies +- External API keys or OAuth tokens must be managed securely via environment variables or secret management tools. +- Any HTTP client library used (e.g., axios, fetch) must be configured with appropriate timeouts, retries, and error handling. +- Logging utilities should be used consistently for request/response tracing, especially for error scenarios. +- No explicit dependencies are declared in the code, but ensure that any imported modules for network requests or logging are correctly configured and versioned. +- Future updates should verify compatibility with Gemini API version changes; monitor Gemini API release notes for breaking changes. + +--- + +**Note:** Given the high churn, maintain rigorous version control and testing for GeminiProvider.ts. Ensure that modifications do not compromise authentication, request integrity, or error handling patterns. \ No newline at end of file diff --git a/packages/app/server/src/providers/AGENTS_this_cluster_encapsu_e8178951.md b/packages/app/server/src/providers/AGENTS_this_cluster_encapsu_e8178951.md new file mode 100644 index 000000000..4d9c1c912 --- /dev/null +++ b/packages/app/server/src/providers/AGENTS_this_cluster_encapsu_e8178951.md @@ -0,0 +1,44 @@ +# Providers (packages/app/server/src/providers) + +## Purpose +This cluster encapsulates provider modules for interfacing with different GPT-based services, specifically GeminiGPT and AnthropicGPT. It abstracts API interactions, enabling flexible integration of multiple LLM providers within the application. + +## Boundaries +- **Belongs here:** Implementation details of GeminiGPTProvider and AnthropicGPTProvider, including API request construction, response parsing, and error handling. +- **Does NOT belong here:** Core application logic, user interface components, or data storage mechanisms. Providers should not handle state management beyond request/response cycles or implement business rules. + +## Invariants +- Each provider must implement a consistent interface (e.g., `sendPrompt()`) to ensure interchangeability. +- API requests must include necessary authentication tokens, which should be securely managed and not hardcoded. +- Responses must be validated for expected structure; null or malformed responses should trigger retries or error propagation. +- No provider should leak sensitive data; ensure proper sanitization and secure handling of API keys. +- Request ordering and concurrency controls are critical if providers are used in parallel; avoid race conditions and ensure thread safety if applicable. +- Churn in provider modules (notably GeminiGPTProvider and AnthropicGPTProvider) is high; expect frequent updates to API endpoints, request schemas, or response formats. + +## Patterns +- Use consistent naming conventions for methods (`sendPrompt`, `initialize`, `shutdown`). +- Error handling should follow a pattern: catch exceptions, log detailed context, and propagate meaningful errors. +- API interactions should be abstracted into helper functions or classes to facilitate testing and mocking. +- Configuration (API keys, endpoints) should be injected via environment variables or configuration files, not hardcoded. +- Asynchronous operations should utilize promises or async/await with proper error catching. +- Maintain clear separation between request construction, response parsing, and error handling logic. + +## Pitfalls +- **Frequent modifications:** GeminiGPTProvider and AnthropicGPTProvider are highly volatile; avoid assumptions about fixed API schemas. +- **Churn risk:** Changes in provider APIs can break request/response handling; implement robust validation and versioning. +- **Null-safety:** Responses may be null or incomplete; always validate before use. +- **Concurrency issues:** If multiple requests are processed simultaneously, ensure thread safety and avoid shared mutable state. +- **Misconfiguration:** Incorrect API keys or endpoints can cause silent failures; enforce validation on startup. +- **Error handling gaps:** Unhandled exceptions can crash request cycles; implement comprehensive try-catch blocks. +- **Resource leaks:** Ensure proper cleanup if providers maintain persistent connections or caches. + +## Dependencies +- **External APIs:** GeminiGPT and AnthropicGPT APIs must be used according to their latest specifications; monitor for updates. +- **Secure storage:** Use environment variables or secret management tools for API keys. +- **Logging:** Implement detailed logging for request/response cycles to facilitate debugging, especially given high churn. +- **Testing frameworks:** Mock provider modules to simulate different API responses and error conditions, ensuring robustness against frequent changes. +- **Configuration management:** Properly load and validate provider-specific settings to prevent runtime errors. + +--- + +**Note:** Given the high churn and frequent updates, agents should prioritize flexible, version-aware request handling and maintain close monitoring of provider API changes to adapt swiftly. \ No newline at end of file diff --git a/packages/app/server/src/providers/AGENTS_this_module_encapsul_e0534192.md b/packages/app/server/src/providers/AGENTS_this_module_encapsul_e0534192.md new file mode 100644 index 000000000..6686b0c70 --- /dev/null +++ b/packages/app/server/src/providers/AGENTS_this_module_encapsul_e0534192.md @@ -0,0 +1,47 @@ +# OpenAIResponsesProvider.ts + +## Purpose +This module encapsulates logic for managing, formatting, and providing responses from OpenAI API interactions within the server. It acts as a central point for response handling, including caching, response parsing, and response validation, ensuring consistent integration with OpenAI services. + +## Boundaries +- **Belongs here:** Response formatting, response caching, response validation, OpenAI API response parsing, response lifecycle management. +- **Does NOT belong here:** Direct API call logic (should be in a dedicated API client), business logic unrelated to response handling, UI rendering, or user interaction code, configuration management (handled elsewhere). + +## Invariants +- Responses must be validated for completeness and correctness before being returned. +- Response caching keys must uniquely identify request parameters to prevent cache pollution. +- Response parsing must handle all expected response formats and gracefully handle unexpected or malformed data. +- Response objects should not be mutated after creation to ensure immutability. +- Null or undefined responses are invalid; must be handled explicitly. +- Response formatting functions must preserve data integrity and avoid data loss. +- Response expiration or cache invalidation policies must be respected to prevent stale data. + +## Patterns +- Use consistent naming conventions: classes ending with `Provider`, methods prefixed with `get`, `fetch`, or `format`. +- Error handling should throw or propagate errors explicitly; avoid silent failures. +- Response parsing should be resilient to API schema changes; include version checks if applicable. +- Cache keys should be constructed from all relevant request parameters to ensure uniqueness. +- Use async/await consistently for asynchronous operations. +- Follow TypeScript strict typing; define interfaces for response shapes. +- Log errors or anomalies during response processing for observability. + +## Pitfalls +- Frequent modifications (high churn) increase risk of introducing cache invalidation bugs or response parsing errors. +- Response parsing assumptions may become outdated if OpenAI API response schemas evolve. +- Cache key construction errors can lead to response mismatches or stale data. +- Null or malformed responses from OpenAI can cause runtime errors if not validated. +- Overlooking response validation invariants may lead to inconsistent downstream behavior. +- Mixing response handling with API call logic violates separation of concerns. +- Not handling error states explicitly can cause silent failures or inconsistent states. + +## Dependencies +- External API client module responsible for making OpenAI API requests (not included here). +- Response validation libraries or custom validation functions to ensure response integrity. +- Caching mechanism (in-memory, Redis, etc.) for response storage; ensure cache keys are well-formed. +- Logging framework for error and anomaly reporting. +- TypeScript types for OpenAI API responses, ensuring type safety and schema validation. +- Configuration management for API endpoints, timeouts, and response handling parameters. + +--- + +**Note:** Given the high churn rate, maintain thorough version control and document response schema expectations explicitly. Regularly review response parsing logic against OpenAI API updates to prevent regressions. \ No newline at end of file diff --git a/packages/app/server/src/resources/AGENTS.md b/packages/app/server/src/resources/AGENTS.md new file mode 100644 index 000000000..df64483ea --- /dev/null +++ b/packages/app/server/src/resources/AGENTS.md @@ -0,0 +1,43 @@ +# [Semantic Cluster: createTavilyTransaction Functions & e2b Module] + +## Purpose +This cluster encapsulates the creation of `Transaction` objects via two overloaded `createTavilyTransaction` functions, handling different input/output types (`TavilyCrawlInput`/`TavilyCrawlOutput` and `TavilyExtractInput`/`TavilyExtractOutput`) and a `cost`. It centralizes transaction instantiation logic, likely for data processing or API interactions, within the `resources/e2b/e2b.ts` module. + +## Boundaries +- **Belongs here:** All logic related to constructing `Transaction` instances from specific input/output pairs and associated costs. +- **Does NOT belong here:** Any logic unrelated to transaction creation, such as data validation, external API calls, or business rules outside transaction instantiation. These should be handled in separate modules or services. + +## Invariants +- The `createTavilyTransaction` functions **must** return a `Transaction` object that correctly encapsulates the provided input, output, and cost. +- The `Transaction` must **not** be null; functions should guarantee a valid, fully populated object. +- The `cost` parameter **must** be a `Decimal` and should be validated or sanitized before use if necessary. +- When multiple versions of `createTavilyTransaction` exist, they **must** handle their respective input/output types correctly without mixing logic. +- The module `e2b.ts` is frequently modified; avoid introducing breaking changes to function signatures or exported entities unless necessary. + +## Patterns +- Use explicit type annotations for all parameters, especially for `input`, `output`, and `cost`. +- Maintain consistent naming conventions: `createTavilyTransaction`, with input/output types clearly indicating their purpose. +- When modifying, respect the existing function overloads; avoid changing parameter order or types unless refactoring. +- Handle errors explicitly; if input validation is needed, throw descriptive exceptions. +- Ensure that the `Transaction` creation logic is atomic and side-effect free. +- Document assumptions about input/output types, especially if transformations are involved. +- Use the `Decimal` type consistently for `cost`, avoiding floating-point inaccuracies. + +## Pitfalls +- **Churn-related risks:** Frequent modifications to `createTavilyTransaction` suggest instability; avoid breaking existing overloads. +- **Type confusion:** Mixing input/output types across overloads can lead to runtime errors; verify correct function usage. +- **Null-safety:** Ensure that `input` and `output` are validated or guaranteed non-null before use. +- **Dependency coupling:** Since the module depends on `Transaction`, ensure that any changes to `Transaction` are compatible with these functions. +- **Overloading ambiguity:** Overloads with similar signatures may cause confusion; document usage clearly. +- **External dependencies:** No external imports are used, but if added, ensure they do not introduce side effects or version conflicts. + +## Dependencies +- **Transaction:** Must be imported and used consistently; understand its constructor or factory pattern. +- **Input/Output Types:** `TavilyCrawlInput`, `TavilyCrawlOutput`, `TavilyExtractInput`, `TavilyExtractOutput` — know their structure and any required transformations. +- **Decimal:** Use the `Decimal` type for `cost`, ensuring proper validation and precision. +- **Module `e2b.ts`:** Contains the core logic; modifications should preserve existing function signatures and behaviors unless refactoring is intentional. + +--- + +**Summary:** +Agents modifying or extending `createTavilyTransaction` functions must respect the input/output contracts, avoid breaking existing overloads, and ensure the `Transaction` objects are correctly instantiated without side effects. The `e2b.ts` module is a hot spot for frequent changes; careful version control and testing are essential. Proper handling of `Decimal` costs and input validation is critical to maintain data integrity. \ No newline at end of file diff --git a/packages/app/server/src/resources/tavily/AGENTS_encapsulates_logic_f_57746cc7.md b/packages/app/server/src/resources/tavily/AGENTS_encapsulates_logic_f_57746cc7.md new file mode 100644 index 000000000..6382a8e57 --- /dev/null +++ b/packages/app/server/src/resources/tavily/AGENTS_encapsulates_logic_f_57746cc7.md @@ -0,0 +1,68 @@ +# Tavily Resources (packages/app/server/src/resources/tavily) + +## Purpose +Encapsulates logic for extracting and crawling Tavily data, enabling data ingestion workflows. It manages the separation between crawling (fetching data) and extraction (processing data), ensuring modularity and clarity in data pipeline stages. + +## Boundaries +- **Belongs here:** + - Core crawling logic in `tavily.ts` (fetching, scheduling, retry policies). + - Data extraction routines in `tavily.ts` (parsing, transforming raw data). + - Configuration and constants specific to Tavily data sources. +- **Does NOT belong here:** + - External API integrations outside Tavily scope (should be abstracted). + - Data storage or database interactions (handled elsewhere). + - UI or client-facing logic. + - Shared utilities unrelated to Tavily data processing. + +## Invariants +- **Data Consistency:** + - Extracted data must conform to predefined schemas; invalid data should trigger errors or be logged for review. +- **Sequential Processing:** + - Crawl and extract functions should follow a predictable sequence; extraction must only process data fetched by the corresponding crawl cycle. +- **Resource Management:** + - Network requests must respect rate limits; retries should implement exponential backoff. +- **Null Safety:** + - All optional fields must be checked before use; avoid null dereferences. +- **Version Stability:** + - Frequent modifications in `tavily.ts` imply the need for rigorous testing to prevent regressions. + +## Patterns +- **Naming:** + - Use clear, descriptive function and variable names reflecting their roles (`fetchTavilyData`, `parseTavilyResponse`). +- **Error Handling:** + - Failures in crawling or extraction should be caught, logged, and optionally retried with exponential backoff. +- **Modularity:** + - Separate concerns: crawling logic in `crawl/tavily.ts`, extraction in `extract/tavily.ts`. +- **Configuration:** + - Use environment variables or config files for endpoints, timeouts, and retry policies. +- **Logging:** + - Log start/end of each major step; include identifiers for traceability. + +## Pitfalls +- **Churn Risks:** + - Frequent changes in `tavily.ts` suggest instability; agents must verify compatibility after each update. +- **Coupling:** + - Tight coupling between crawl and extract modules can cause cascading failures; ensure loose interfaces. +- **Null/Undefined Data:** + - Data fetched may be incomplete or malformed; validate before processing. +- **Rate Limits & Retries:** + - Ignoring rate limits or retry policies can cause bans or inconsistent data. +- **Version Mismatch:** + - Changes in external Tavily API may break extraction; monitor external API updates. + +## Dependencies +- **External APIs:** + - Tavily data source endpoints (must be configured correctly). +- **HTTP Client Libraries:** + - Use consistent, reliable libraries for network requests, with built-in retry support if possible. +- **Logging Framework:** + - Ensure logs are structured and include context (e.g., request IDs). +- **Configuration Management:** + - Use environment variables or config files for endpoint URLs, timeouts, and retry counts. +- **Testing Framework:** + - Rigorously test both modules after each change, especially given high churn. + +--- + +**Summary:** +Agents working on the Tavily resource modules must understand the separation of concerns between crawling and extraction, the importance of data validation, and the need for robust error handling and retry logic. Frequent modifications necessitate vigilant testing and validation to prevent regressions. Proper configuration and logging are critical for maintainability and debugging. \ No newline at end of file diff --git a/packages/app/server/src/resources/tavily/AGENTS_this_area_encapsulat_b202989c.md b/packages/app/server/src/resources/tavily/AGENTS_this_area_encapsulat_b202989c.md new file mode 100644 index 000000000..f6727d997 --- /dev/null +++ b/packages/app/server/src/resources/tavily/AGENTS_this_area_encapsulat_b202989c.md @@ -0,0 +1,45 @@ +# Tavily Resource Calculation + +## Purpose +This area encapsulates the logic for calculating the actual cost of Tavily data extraction, specifically via the `calculateTavilyExtractActualCost` function. It manages cost computations based on input parameters and outputs precise decimal values, integral to billing or resource tracking. + +## Boundaries +- **Belongs here:** Cost calculation logic, input/output data structures (`TavilyExtractInput`, `TavilyExtractOutput`), and the `calculateTavilyExtractActualCost` function. +- **Does NOT belong here:** External data fetching, network requests, or database interactions; these should be handled outside this module. Utility functions unrelated to cost calculation, or UI rendering, are outside scope. + +## Invariants +- The function must always return a `Decimal` representing the cost; no nulls or undefined. +- Inputs must conform to `TavilyExtractInput` schema; invalid inputs should be validated before invocation. +- The output should reflect the latest calculation logic; avoid caching unless explicitly required. +- Cost calculations should respect the precision constraints of `Decimal`; avoid floating-point inaccuracies. +- The module `packages/app/server/src/resources/tavily/search/tavily.ts` may contain supporting search or lookup functions, but core calculation logic must be isolated. +- No side effects; the function should be pure, with no external state modifications. +- The function's behavior must be deterministic given identical inputs. + +## Patterns +- Use `Decimal` for all monetary or precise calculations; avoid JavaScript number types for currency. +- Follow naming conventions: `calculateTavilyExtractActualCost` clearly indicates a computation. +- Handle edge cases explicitly, e.g., zero or negative input values, with validation or safeguards. +- Document assumptions about input fields within `TavilyExtractInput`. +- Maintain idempotency; repeated calls with same inputs produce same outputs. +- Use explicit error handling for invalid inputs, but avoid throwing exceptions unless critical. +- Keep the calculation logic isolated; avoid embedding side effects or external calls within the function. + +## Pitfalls +- Frequent modifications (5 versions) suggest high churn; ensure changes are well-tested. +- Be cautious of floating-point errors; always use `Decimal` for calculations. +- Watch for null or undefined inputs; validate early. +- Avoid tight coupling with unrelated modules; dependencies should be explicit and minimal. +- Do not assume input data is sanitized; validate inputs before calculation. +- Beware of race conditions if the function is invoked concurrently; ensure thread safety if applicable. +- Do not cache results internally unless explicitly designed; stale data can cause incorrect billing. +- When modifying, ensure to update related tests to reflect new logic or invariants. + +## Dependencies +- **External:** `Decimal` library must be used for all calculations to ensure precision. +- **Internal:** The module `packages/app/server/src/resources/tavily/search/tavily.ts` may provide auxiliary search or lookup functions; use them cautiously, ensuring they do not introduce side effects or violate invariants. +- Validate that `TavilyExtractInput` and `TavilyExtractOutput` schemas are adhered to before invoking the calculation function to prevent runtime errors. + +--- + +**Note:** Given the high churn, maintain clear version control and thorough testing when modifying `calculateTavilyExtractActualCost` or related entities. Ensure that any change preserves the deterministic and precise nature of cost calculations. \ No newline at end of file diff --git a/packages/app/server/src/resources/tavily/AGENTS_this_area_manages_7a4be269.md b/packages/app/server/src/resources/tavily/AGENTS_this_area_manages_7a4be269.md new file mode 100644 index 000000000..32aab354e --- /dev/null +++ b/packages/app/server/src/resources/tavily/AGENTS_this_area_manages_7a4be269.md @@ -0,0 +1,45 @@ +# Tavily Search Cost Calculation + +## Purpose +This area manages the computation of the actual cost for Tavily crawling operations, encapsulated in the `calculateTavilyCrawlActualCost` function and related types. It provides the logic to derive a `Decimal` value representing the resource expenditure or effort associated with a specific crawl input. + +## Boundaries +- **Belongs here:** Implementation of `calculateTavilyCrawlActualCost`, including input validation, cost computation logic, and output formatting. +- **Does NOT belong here:** UI presentation, API routing, or higher-level orchestration; these should invoke this function but not contain its logic. +- **Types and interfaces** (`TavilyCrawlInput`, `TavilyCrawlOutput`) are defined in `types.ts` and should be considered part of the contract for this calculation. +- **External dependencies** like `Decimal` are used strictly for precise arithmetic; avoid converting to/from native number types within this module. + +## Invariants +- The function must **never** return a negative cost. +- Inputs must be validated to prevent null/undefined values; invalid inputs should throw or handle errors explicitly. +- The `Decimal` output must be normalized (e.g., fixed scale) before returning. +- The calculation should **not** mutate input objects. +- The cost calculation logic must respect the defined semantics of `TavilyCrawlInput` and `TavilyCrawlOutput`. + +## Patterns +- Use consistent naming: `calculateTavilyCrawlActualCost`, `input`, `output`. +- Perform early validation of `input` fields; throw descriptive errors if invalid. +- Use `Decimal` arithmetic methods (`add`, `mul`, `div`) for all calculations. +- Avoid implicit type coercion; ensure all numeric values are `Decimal` or converted explicitly. +- Document assumptions about input fields influencing cost. +- Maintain idempotency: repeated calls with the same input produce the same output. +- Follow existing code style: indentation, error handling, and comments. + +## Pitfalls +- **Churn hotspots**: `types.ts` and `calculateTavilyCrawlActualCost` are frequently modified; ensure backward compatibility. +- **Incorrect assumptions** about input fields' presence or default values can lead to incorrect cost calculations. +- **Neglecting validation** can cause runtime errors or invalid cost outputs. +- **Misuse of `Decimal`**: converting to native number types or losing precision can introduce subtle bugs. +- **Ignoring null-safety**: missing null checks on input fields may cause exceptions. +- **Overcomplicating logic**: keep calculations straightforward; complex branching increases error risk. +- Changes in dependencies (e.g., `Decimal`) may require updates to calculation logic. + +## Dependencies +- **Decimal** library: Use its methods (`add`, `sub`, `mul`, `div`, `toFixed`) for all arithmetic to ensure precision. +- **Types (`TavilyCrawlInput`, `TavilyCrawlOutput`)**: Understand their structure, optional fields, and default values. +- **Error handling conventions**: Follow existing patterns for validation errors or exceptional states. +- **No external dependencies** beyond `Decimal`; ensure all logic is self-contained or properly imported. + +--- + +**Note:** When modifying `calculateTavilyCrawlActualCost`, verify input validation, adhere to invariants, and test with boundary cases to prevent subtle bugs in cost computation. \ No newline at end of file diff --git a/packages/app/server/src/resources/tavily/AGENTS_this_cluster_manages_978bb074.md b/packages/app/server/src/resources/tavily/AGENTS_this_cluster_manages_978bb074.md new file mode 100644 index 000000000..d63c29fda --- /dev/null +++ b/packages/app/server/src/resources/tavily/AGENTS_this_cluster_manages_978bb074.md @@ -0,0 +1,39 @@ +# Tavily Resources (packages/app/server/src/resources/tavily) + +## Purpose +This cluster manages data types related to Tavily's extraction and crawling processes, defining core data structures for these operations. It facilitates consistent data handling across extraction and crawling modules, enabling integration and processing workflows. + +## Boundaries +- **Belongs here:** Type definitions for extraction (`extract/types.ts`) and crawling (`crawl/types.ts`), including interfaces, enums, and data schemas. +- **Does NOT belong here:** Implementation logic, API endpoints, runtime behavior, or business logic; these are purely data contracts. Any operational code or service logic should reside outside these type files. + +## Invariants +- **Type Consistency:** All data types must adhere strictly to their defined interfaces; no partial or malformed objects should be accepted. +- **Null Safety:** Fields marked as non-optional must always be present; optional fields can be omitted but, if present, must conform to their types. +- **Versioning:** Given high-churn (5 versions each), avoid breaking changes; prefer additive modifications and deprecations over removals. +- **Data Integrity:** Data structures should not contain cyclic references unless explicitly supported; avoid circular dependencies between types. +- **Immutable Contracts:** Types should be designed to be immutable once instantiated, preventing accidental mutations. + +## Patterns +- **Naming:** Use clear, descriptive names matching the entity purpose, e.g., `ExtractResult`, `CrawlStatus`. +- **Error Handling:** When extending types, include error or status fields explicitly; do not embed error states within core data types. +- **Versioning:** Use version tags or comments to track evolution; avoid breaking changes in existing types. +- **Extensibility:** Use union types or extendable interfaces for optional or evolving fields. +- **Documentation:** Each type should include comments explaining its role, especially for complex or non-obvious fields. +- **Separation of Concerns:** Keep extraction and crawling types isolated; avoid sharing types unless necessary, to prevent coupling. + +## Pitfalls +- **Churn Risks:** Frequent modifications increase risk of introducing inconsistencies; document breaking changes clearly. +- **Type Mismatches:** Inconsistent use of optional vs. required fields can cause runtime errors; enforce strict typing. +- **Circular Dependencies:** Avoid cross-referencing types between `extract/types.ts` and `crawl/types.ts` unless explicitly designed. +- **Version Drift:** Be cautious when updating types; ensure consumers are compatible, especially given high churn. +- **Misuse of Types:** Do not embed operational logic or side effects within data types; keep them pure data contracts. +- **Nullability Assumptions:** Do not assume optional fields are always present; validate presence before use. + +## Dependencies +- **External:** None directly; however, if future extensions involve external libraries (e.g., validation, serialization), ensure they are compatible with the data structures. +- **Internal:** These types are foundational; avoid tight coupling with implementation logic. When extending, respect existing invariants and patterns. + +--- + +*Note:* Given the high modification frequency, maintain rigorous version control and documentation for each type to facilitate safe evolution and integration. \ No newline at end of file diff --git a/packages/app/server/src/schema/AGENTS_defines_and_manages_0c612168.md b/packages/app/server/src/schema/AGENTS_defines_and_manages_0c612168.md new file mode 100644 index 000000000..f0eea11d6 --- /dev/null +++ b/packages/app/server/src/schema/AGENTS_defines_and_manages_0c612168.md @@ -0,0 +1,41 @@ +# Schema for Route Intent Node + +## Purpose +Defines and manages the schema structure for route-related data within the application, enabling consistent validation, serialization, and integration of route metadata. It encapsulates the data contracts that route configurations must adhere to, facilitating reliable route handling and extension. + +## Boundaries +- **Belongs here:** Schema definitions for route configuration, validation rules, and associated types in `schemaForRoute.ts`. +- **Does NOT belong here:** Business logic, route handler implementations, or middleware; these should reside in separate modules. Data fetching or persistence logic is outside this schema's scope. + +## Invariants +- The schema must always be valid JSON Schema or TypeScript types that accurately reflect route configuration constraints. +- Route schemas should be immutable post-initialization to prevent runtime inconsistencies. +- All route-related data must conform to the defined schema; no partial or malformed data should be accepted. +- The schema should not depend on external mutable state; all defaults and constraints are statically defined. +- Versioning of schema definitions (not explicitly shown but implied by hot-churn) must preserve backward compatibility unless explicitly deprecated. + +## Patterns +- Use explicit TypeScript interfaces or JSON Schema definitions for route data. +- Follow naming conventions: `schemaForRoute.ts` indicates schema definitions are centralized; maintain consistent naming. +- Validate route data at entry points using the schema before processing. +- Handle validation errors explicitly, providing clear feedback for debugging. +- Use versioned schema if multiple route versions are supported, especially given high churn. +- Document schema fields with comments for clarity, especially optional or complex fields. + +## Pitfalls +- Frequent modifications (hot-churn) increase risk of introducing breaking changes; enforce strict validation. +- Overlooking null-safety: ensure optional fields are properly marked; avoid assumptions about presence. +- High coupling is not detected, but be cautious when extending schema to avoid breaking existing contracts. +- Avoid implicit assumptions about route data; always validate against schema. +- Be aware that schema evolution may cause compatibility issues; plan migrations carefully. +- Do not embed business logic or side effects within schema definitions. + +## Dependencies +- No external dependencies are explicitly imported; rely solely on TypeScript types or JSON Schema standards. +- When integrating with validation libraries, ensure they support the schema format used. +- Maintain consistency with other schema modules in the codebase for interoperability. +- Use validation functions that are compatible with the schema format to enforce data integrity. + +--- + +**Note:** Given the high churn hotspot in `schemaForRoute.ts`, agents should monitor changes closely, document schema updates, and ensure backward compatibility where necessary. \ No newline at end of file diff --git a/packages/app/server/src/schema/AGENTS_defines_data_schemas_b870fcfd.md b/packages/app/server/src/schema/AGENTS_defines_data_schemas_b870fcfd.md new file mode 100644 index 000000000..3ad9f0994 --- /dev/null +++ b/packages/app/server/src/schema/AGENTS_defines_data_schemas_b870fcfd.md @@ -0,0 +1,46 @@ +# Schema Code Area (packages/app/server/src/schema) + +## Purpose +Defines data schemas and validation logic for image processing (gemini.ts) and chat completions (completions.ts), establishing structured data contracts used throughout the server. + +## Boundaries +- **Belongs here:** JSON schema definitions, type interfaces, validation functions, and related utility functions for image and chat data. +- **Does NOT belong here:** Business logic, API route handlers, database interactions, or UI components. Keep schema definitions isolated from operational code. + +## Invariants +- All JSON schemas must be valid and conform to JSON Schema standards (`json_schema` dependency). +- Data objects must satisfy their respective schemas before processing; validation should be enforced at entry points. +- Null values are disallowed unless explicitly permitted in schema definitions. +- The order of properties in schemas should follow the defined sequence to ensure consistency. +- Schema versioning must be managed carefully; frequent modifications (noted in hot-churn modules) require backward compatibility checks. +- Dependencies like `json_object` and `format` are used for schema validation and formatting; their correct usage ensures data integrity. + +## Patterns +- Use consistent naming conventions: `CamelCase` for types/interfaces, `snake_case` for schema files. +- Validation functions should be invoked synchronously where possible; asynchronous validation is only for external or complex checks. +- Error handling: return detailed validation errors, avoid silent failures. +- When extending schemas, use composition (`allOf`, `anyOf`) rather than duplication. +- Maintain clear separation between schema definitions and utility functions to facilitate testing and updates. +- Use `needed` and `section` modules for conditional or optional schema parts, following existing patterns. + +## Pitfalls +- Frequent modifications in `gemini.ts` and `completions.ts` increase risk of schema drift or versioning issues. +- Avoid circular dependencies between modules; `json_schema` and `json_object` should be used carefully to prevent import cycles. +- Null-safety: ensure schemas explicitly specify `null` where nullable; implicit nullability can cause runtime errors. +- Be cautious with external dependencies (`exist`, `tools`); improper usage can lead to validation failures or inconsistent data. +- Schema evolution must consider existing data; breaking changes can cause deserialization errors. +- Do not embed business logic within schema files; keep them purely declarative. + +## Dependencies +- **exist:** Use for existence checks within validation logic; ensure proper null/undefined handling. +- **format:** Apply for string formatting, pattern matching, and data normalization within schemas. +- **json_object:** Facilitate conversion between JSON data and internal representations; ensure consistent usage. +- **json_schema:** Core for defining and validating JSON schemas; adhere to JSON Schema standards. +- **needed:** Manage optional or conditional schema parts; follow existing patterns for optional fields. +- **section:** Organize schema components into logical sections; use for clarity and modularity. +- **text:** Use for string validation, error messages, and user-facing descriptions. +- **tools:** Utility functions for schema manipulation, validation, and data transformations; leverage as per existing patterns. + +--- + +**Note:** Given the high churn in both modules, agents should prioritize understanding schema versioning strategies and validation patterns to prevent introducing breaking changes or inconsistencies. \ No newline at end of file diff --git a/packages/app/server/src/services/AGENTS_encapsulates_core_ac_0a945379.md b/packages/app/server/src/services/AGENTS_encapsulates_core_ac_0a945379.md new file mode 100644 index 000000000..fcc75e253 --- /dev/null +++ b/packages/app/server/src/services/AGENTS_encapsulates_core_ac_0a945379.md @@ -0,0 +1,42 @@ +# AccountingService.ts + +## Purpose +Encapsulates core accounting logic related to supported models (SupportedModel, SupportedVideoModel, SupportedImageModel), providing methods for financial calculations, model validation, and transaction handling within the server's service layer. + +## Boundaries +- **Belongs to:** Business logic layer managing accounting operations tied to supported models. +- **Does NOT belong to:** Data persistence (handled elsewhere, e.g., repositories), UI rendering, or external API integrations outside the defined dependencies. +- **Model dependencies:** Relies on SupportedModel, SupportedVideoModel, SupportedImageModel for validation and processing; these should be stable and well-defined. +- **External dependencies:** Uses 'O' (likely an external library or utility); ensure correct import and versioning to prevent runtime issues. +- **Error handling:** Must consistently handle validation failures and external errors, propagating meaningful exceptions. + +## Invariants +- **Supported Model Contracts:** Any model passed to methods must conform to the SupportedModel interface; validation should be enforced before processing. +- **Model Validation:** SupportedVideoModel and SupportedImageModel must be validated against their respective schemas before use. +- **Null Safety:** Inputs to methods must be checked for null/undefined; return values should be explicitly defined. +- **Transaction Integrity:** Operations that modify state should be atomic; partial failures must roll back or be handled gracefully. +- **External Calls:** Calls to external entities (via 'O') must handle potential failures, retries, or fallbacks to maintain consistency. +- **Churn Sensitivity:** Given high modification frequency, avoid adding complex logic without clear version control; document assumptions explicitly. + +## Patterns +- **Naming:** Use clear, descriptive method names aligned with domain language (e.g., `calculateTotal`, `validateModels`). +- **Validation:** Always validate models with their respective schemas before processing; fail fast on invalid data. +- **Error Handling:** Wrap external calls with try-catch; throw domain-specific exceptions with meaningful messages. +- **Dependency Usage:** Reference SupportedModel, SupportedVideoModel, SupportedImageModel explicitly; avoid tight coupling beyond interface contracts. +- **Code Style:** Maintain consistency with existing code conventions; avoid feature envy by minimizing external calls within methods. +- **Churn Management:** Document reasons for frequent modifications; consider abstracting repetitive logic to helper functions. + +## Pitfalls +- **Over-reliance on external entities:** Excessive calls to external dependencies ('O') can cause performance bottlenecks or instability; cache or batch calls where possible. +- **Ignoring model validation:** Proceeding with invalid models can cause downstream errors; enforce validation strictly. +- **High churn areas:** Frequent updates (5 versions) suggest instability; avoid complex logic that complicates maintenance. +- **Null/undefined assumptions:** Failing to check inputs can lead to runtime errors; enforce null safety. +- **Transaction boundaries:** Not ensuring atomicity in multi-step operations risks inconsistent state. +- **Coupling:** Tight coupling with specific models or external libraries can hinder refactoring; abstract interfaces where feasible. + +## Dependencies +- **SupportedModel, SupportedVideoModel, SupportedImageModel:** Use these interfaces for validation and processing; ensure they are correctly imported and versioned. +- **External 'O':** Understand its purpose (utility, external API, etc.); use according to documented patterns. +- **Validation schemas:** Ensure schemas for video and image models are up-to-date and validated before processing. +- **Error handling utilities:** Use consistent exception classes or error wrappers to maintain predictable failure modes. +- **Version control:** Track changes to this service carefully due to high churn; document reasons for modifications to facilitate maintenance. \ No newline at end of file diff --git a/packages/app/server/src/services/AGENTS_encapsulates_core_lo_258fbd59.md b/packages/app/server/src/services/AGENTS_encapsulates_core_lo_258fbd59.md new file mode 100644 index 000000000..1b547b239 --- /dev/null +++ b/packages/app/server/src/services/AGENTS_encapsulates_core_lo_258fbd59.md @@ -0,0 +1,47 @@ +# EchoControlService.ts + +## Purpose +Encapsulates core logic for managing echo control functionalities within the server, handling real-time state updates, command processing, and interaction with other services related to echo suppression or modulation. + +## Boundaries +- **Belongs:** All echo control operations, including state management, command execution, and related validation. +- **Excludes:** External communication (e.g., network calls), UI interactions, or persistent storage—these should be handled by separate modules or layers. +- **Should not:** Access or modify unrelated services or global state outside its scope; maintain strict encapsulation of echo control logic. + +## Invariants +- The service must always maintain a consistent internal state representing the current echo control status. +- Commands processed must adhere to predefined formats; invalid commands should trigger explicit error handling. +- State updates should be atomic; partial updates risk inconsistent behavior. +- Null or undefined inputs for critical parameters (e.g., command data) must be rejected immediately. +- Lifecycle management: ensure cleanup of timers, subscriptions, or resources during shutdown or reinitialization. +- No external side effects should occur within core methods; side effects are to be delegated or explicitly documented. + +## Patterns +- Use clear, descriptive method naming (e.g., `processCommand()`, `updateState()`, `initialize()`). +- Follow consistent error handling: throw or reject with explicit error messages; avoid silent failures. +- Adopt a command pattern for processing input commands, validating before execution. +- Maintain strict typing; leverage TypeScript interfaces for command and state objects. +- Use dependency injection for external services if applicable, even if none are currently listed. +- Document assumptions about input data structures and expected state transitions. + +## Pitfalls +- Frequent modifications (5 versions) suggest high churn; avoid introducing side effects that complicate state consistency. +- Be cautious with concurrency: avoid race conditions when updating shared state. +- Do not assume external dependencies; code should be resilient to missing or malformed inputs. +- Watch out for null/undefined inputs, especially in command processing. +- Avoid tight coupling: do not embed logic that depends on unrelated modules or global state. +- Be wary of incomplete error handling—ensure all failure modes are explicitly managed. +- Given no dependencies, ensure internal logic remains decoupled and testable. + +## Dependencies +- Currently, none external; future integrations (e.g., with network modules, hardware controllers) should follow explicit interfaces. +- When integrating external dependencies, follow dependency inversion principles: + - Inject dependencies via constructor or setters. + - Validate external inputs thoroughly. + - Handle failures gracefully, maintaining internal state integrity. +- Maintain testability by mocking dependencies during unit tests. + +--- + +**Summary:** +Agents working with `EchoControlService.ts` must understand its role as a self-contained, stateful component managing echo control commands with strict invariants, error handling, and encapsulation. Careful attention to concurrency, error propagation, and churn-prone areas is essential to maintain stability and clarity. \ No newline at end of file diff --git a/packages/app/server/src/services/AGENTS_encapsulates_the_log_b3cee08a.md b/packages/app/server/src/services/AGENTS_encapsulates_the_log_b3cee08a.md new file mode 100644 index 000000000..84b80c706 --- /dev/null +++ b/packages/app/server/src/services/AGENTS_encapsulates_the_log_b3cee08a.md @@ -0,0 +1,48 @@ +# HandleStreamService (packages/app/server/src/services/HandleStreamService.ts) + +## Purpose +Encapsulates the logic for managing stream handling, including establishing, maintaining, and terminating stream connections, with a focus on robust data flow control and error resilience within the server. + +## Boundaries +- **Belongs here:** Stream lifecycle management, data piping, error handling, connection cleanup, and resource disposal related to stream processing. +- **Does NOT belong here:** Business logic unrelated to streaming (e.g., domain-specific data transformations), external API calls outside stream context, UI interactions, or configuration management not directly tied to stream handling. + +## Invariants +- The `pipeline` function must be used to connect streams, ensuring proper error propagation and cleanup. +- Streams must be properly closed or destroyed on errors or completion to prevent resource leaks. +- Stream data flow should respect backpressure; avoid unbounded buffering. +- The service must handle null or undefined stream inputs gracefully, avoiding runtime exceptions. +- Any errors in stream processing should be caught and logged, with appropriate cleanup, without crashing the server. +- Connection states (established, active, closed) must be consistently tracked to prevent dangling or double cleanup. +- The class must not modify streams outside its control unless explicitly designed to do so. + +## Patterns +- Use the `pipeline` utility for stream chaining; always handle its callback or promise rejection. +- Follow naming conventions: methods like `startHandling`, `stopHandling`, `resetStream`. +- Error handling should be centralized; do not swallow errors silently. +- Use explicit state flags to track stream status. +- When modifying streams, clone or wrap streams to preserve original state. +- Log significant lifecycle events (start, stop, error) with context. +- Implement idempotent cleanup methods to avoid double cleanup. + +## Pitfalls +- Forgetting to handle errors from `pipeline`, leading to unhandled promise rejections. +- Not cleaning up streams on error, causing memory leaks. +- Modifying streams outside the class scope, breaking invariants. +- Relying on implicit assumptions about stream states; always check nullity and state flags. +- Frequent churn indicates evolving API; avoid tight coupling to specific stream implementations. +- Overlooking backpressure management, risking memory bloat. +- Ignoring external dependencies like `pipeline`, which may have platform-specific behaviors. +- Failing to log or monitor stream errors, complicating debugging. +- Modifying streams concurrently without synchronization, risking race conditions. + +## Dependencies +- **`pipeline`**: Use as the primary method for connecting streams; handle its promise or callback to manage errors. +- External stream modules should conform to Node.js stream API; validate stream types before piping. +- Ensure `pipeline` is correctly imported and compatible with the Node.js version in use. +- Avoid external dependencies that modify stream behavior unexpectedly; prefer standard Node.js streams or well-maintained wrappers. +- Use internal logging facilities for error reporting; do not rely solely on `pipeline` errors for observability. + +--- + +**Note:** This node assumes familiarity with Node.js stream API, the `pipeline` utility, and common patterns for stream lifecycle management. It emphasizes robust error handling, resource cleanup, and adherence to stream invariants critical for server stability. \ No newline at end of file diff --git a/packages/app/server/src/services/AGENTS_handles_creation_of_b1621c7b.md b/packages/app/server/src/services/AGENTS_handles_creation_of_b1621c7b.md new file mode 100644 index 000000000..ebbc6de1f --- /dev/null +++ b/packages/app/server/src/services/AGENTS_handles_creation_of_b1621c7b.md @@ -0,0 +1,46 @@ +# GenerateCdpJwt Intent Node + +## Purpose +Handles creation of JWT tokens for Coinbase Commerce Data Platform (CDP) API authentication, encapsulating token generation logic with configurable parameters. Ensures tokens are generated with correct claims, expiration, and request context. + +## Boundaries +- **Belongs here:** JWT generation logic, including request metadata (method, path, host), expiration, and token signing. +- **Does NOT belong:** Authentication flows unrelated to JWT creation, token validation, or key management; external API request handling; user session management; or storage of tokens. + +## Invariants +- The `generateCdpJwt` function must always produce a valid JWT signed with the correct secret/key, using the `generateJwt` dependency. +- `expiresIn` defaults to `1200000000` (approx. 38 years); must be explicitly set or validated to prevent unintended long-lived tokens. +- `requestHost` defaults to `'api.cdp.coinbase.com'`; should be overridden only when targeting different endpoints. +- The input `GenerateCdpJwtInput` must be validated for presence and correctness before invocation. +- JWT claims must include all necessary request context (method, path, host) to ensure proper API authorization. +- No external dependencies other than `generateJwt` should influence token payload or signing process. +- The function must be async, ensuring proper handling of the `generateJwt` promise. + +## Patterns +- Use `generateJwt` to sign tokens, passing payload with request metadata and expiration. +- Default parameters should be explicitly set for `requestHost` and `expiresIn`. +- Maintain strict input validation for `GenerateCdpJwtInput` before calling `generateJwt`. +- Follow naming conventions: function named `generateCdpJwt`, input interface `GenerateCdpJwtInput`. +- Handle errors from `generateJwt` gracefully, propagating or logging as per project standards. +- Keep token expiration configurable but within safe bounds; avoid excessively long durations unless explicitly intended. +- Use `toJsonSafe.ts` for serializing payloads if needed, ensuring no data loss or serialization errors. + +## Pitfalls +- Frequently modified: `generateCdpJwt`, `GenerateCdpJwtInput`, increasing risk of inconsistent updates. +- Hardcoded default `expiresIn` may lead to security issues if not overridden; document this clearly. +- Forgetting to validate input fields can produce invalid tokens or runtime errors. +- Relying solely on `generateJwt` without verifying its implementation or error handling can cause silent failures. +- Not updating related modules (`facilitatorService.ts`, `constants.ts`) when token logic changes. +- Churn in `generateCdpJwt` suggests evolving requirements; ensure backward compatibility if used elsewhere. +- Overlooking request context (method, path, host) can produce invalid or insecure tokens. + +## Dependencies +- **generateJwt:** Core dependency for signing JWTs; must be used with correct payload structure. +- **toJsonSafe.ts:** Utility for safe serialization of payload data; ensure payloads are serialized consistently. +- **Constants.ts:** May contain constants related to token durations or secret keys; verify usage aligns with current security policies. +- **External API endpoints:** `api.cdp.coinbase.com` as default; confirm endpoint correctness for environment (prod/staging). +- **Security considerations:** Ensure secret keys used in `generateJwt` are securely stored and accessed; avoid hardcoding secrets. + +--- + +**Note:** Always verify the latest security standards for JWT handling, including key rotation, claim validation, and expiration management, especially given the high churn rate indicating evolving security requirements. \ No newline at end of file diff --git a/packages/app/server/src/services/AGENTS_provides_an_abstract_8d0894d7.md b/packages/app/server/src/services/AGENTS_provides_an_abstract_8d0894d7.md new file mode 100644 index 000000000..0fa8db9e5 --- /dev/null +++ b/packages/app/server/src/services/AGENTS_provides_an_abstract_8d0894d7.md @@ -0,0 +1,44 @@ +# DbService.ts - Database Service Module + +## Purpose +Provides an abstraction layer for database interactions, encapsulating connection management, query execution, and transaction handling within the application server. Ensures consistent access patterns and data integrity. + +## Boundaries +- **Belongs to:** Core data access layer; handles direct database operations. +- **Does NOT belong to:** Business logic, API controllers, or request routing; those should invoke this service but not contain database code. +- **External integrations:** Should not directly depend on external APIs or services; any such dependencies must be abstracted or mocked for testing. +- **Configuration:** Database connection parameters and credentials are managed outside this module, typically via environment variables or configuration files. + +## Invariants +- **Connection Management:** Always establish a connection before executing queries; release/close connections after use unless using persistent connection pools. +- **Error Handling:** Failures during query execution must be caught and propagated with meaningful error messages; do not swallow exceptions. +- **Null Safety:** Query results may contain nulls; handle nulls explicitly to avoid runtime errors. +- **Hashing Dependency:** When hashing is used (e.g., for password storage or data integrity), it must follow secure, industry-standard algorithms and salting practices. +- **Versioning:** The module is frequently modified; avoid breaking existing interfaces or assumptions. Maintain backward compatibility where possible. + +## Patterns +- **Naming:** Use clear, descriptive method names (e.g., `getUserById`, `saveRecord`) aligned with their purpose. +- **Async/Await:** All database calls are asynchronous; agents must await calls properly. +- **Error Propagation:** Throw or return errors explicitly; do not suppress. +- **Transactions:** Use transaction patterns for multi-step operations; ensure rollback on failure. +- **Configuration:** Sensitive info like credentials should be injected via environment variables or secure configs, not hardcoded. +- **Hashing:** Use the imported `hashing` module for password or data hashing; follow best practices for security. + +## Pitfalls +- **Churn Risks:** The module is frequently modified; avoid introducing breaking changes, especially to exported interfaces. +- **Resource Leaks:** Forgetting to close or release database connections can cause leaks; prefer connection pools. +- **Concurrency:** Be cautious with shared state; avoid race conditions in connection handling. +- **Error Handling:** Inconsistent error handling can lead to unhandled exceptions or silent failures. +- **Hashing Misuse:** Using insecure hashing algorithms or improper salting can compromise security. +- **Dependency Misuse:** Directly importing external modules without understanding their API can cause bugs; adhere to documented usage patterns. +- **Testing:** Since the module depends on external database state, ensure proper mocking/stubbing in tests to prevent flaky tests. + +## Dependencies +- **O:** Core ORM or database driver; agents must understand its API for query execution. +- **hashing:** Used for secure data handling; must be used with industry-standard algorithms (e.g., bcrypt, argon2) and proper salting. +- **Configuration Management:** External environment variables or config files supply database credentials; agents must handle missing or invalid configs gracefully. +- **Error Handling Libraries:** If used, understand their conventions for propagating and formatting errors. + +--- + +**Note:** Given the high churn, agents should monitor for API changes, especially in method signatures or connection handling patterns, and verify hashing practices remain secure. \ No newline at end of file diff --git a/packages/app/server/src/services/facilitator/AGENTS_defines_core_typescr_bc4c66a6.md b/packages/app/server/src/services/facilitator/AGENTS_defines_core_typescr_bc4c66a6.md new file mode 100644 index 000000000..861080fbb --- /dev/null +++ b/packages/app/server/src/services/facilitator/AGENTS_defines_core_typescr_bc4c66a6.md @@ -0,0 +1,44 @@ +# Facilitator Types Module (packages/app/server/src/services/facilitator/x402-types.ts) + +## Purpose +Defines core TypeScript types, interfaces, and data structures used within the facilitator service, enabling consistent data contracts and type safety across facilitator-related operations. + +## Boundaries +- **Belongs here:** Type definitions, enums, interfaces, utility types specific to facilitator logic. +- **Does NOT belong here:** Implementation logic, function implementations, runtime behavior, or business logic—these should reside in service or handler modules. Avoid placing runtime code or business rules in this types file. + +## Invariants +- All type definitions must be explicitly typed; avoid implicit `any`. +- Enums should have explicit string or numeric values to prevent ambiguity. +- Interfaces representing data objects must include all required fields; optional fields should be clearly marked. +- Null-safety: fields that are optional or nullable must be explicitly marked (`?` or `| null`). +- Types should be versioned or annotated if they evolve frequently, to prevent breaking consumers. +- Consistency in naming conventions: e.g., suffixes like `Dto`, `Payload`, `Config` to clarify purpose. +- Avoid circular references between types; use type aliases or interfaces to break cycles. + +## Patterns +- Use PascalCase for type and interface names. +- Prefix enum values with the enum name for clarity (e.g., `X402TypeEnum.Value`). +- When defining union types, prefer string literal unions over enums for flexibility unless strict validation is needed. +- Document each type/interface with JSDoc comments explaining its purpose and constraints. +- Maintain a clear separation between data shapes (types) and runtime validation (which should be handled elsewhere). +- Use readonly modifiers for data structures that should be immutable. +- For frequently changing types (noted hot spots), consider versioning or comments indicating stability. + +## Pitfalls +- Frequent modifications (hot spots) increase risk of breaking consumers; document changes carefully. +- Nullability and optional fields are common sources of runtime errors; enforce strict null checks. +- Overusing `any` or loose types can lead to type safety erosion; avoid unless absolutely necessary. +- Circular dependencies or overly complex nested types can complicate maintenance. +- Misalignment between type definitions and actual runtime data can cause subtle bugs; ensure types are kept in sync with runtime validation schemas. +- Be cautious with enum values—changing them can break consumers relying on specific string/numeric literals. +- Avoid defining types that are too broad or too narrow, which can cause mismatch issues. + +## Dependencies +- This module does not depend on external libraries; it solely defines TypeScript types. +- Ensure that any runtime validation or serialization logic consuming these types adheres to the defined contracts. +- If external validation libraries (e.g., `zod`, `io-ts`) are used elsewhere, maintain alignment between runtime schemas and these type definitions. + +--- + +**Note:** Given the high churn hotspot at this file, prioritize documenting versioning strategies and change impact assessments for modifications to prevent breaking dependent code. \ No newline at end of file diff --git a/packages/app/server/src/services/facilitator/AGENTS_this_area_manages_ff912fbc.md b/packages/app/server/src/services/facilitator/AGENTS_this_area_manages_ff912fbc.md new file mode 100644 index 000000000..21ba5676f --- /dev/null +++ b/packages/app/server/src/services/facilitator/AGENTS_this_area_manages_ff912fbc.md @@ -0,0 +1,38 @@ +# Facilitator Service Area + +## Purpose +This area manages facilitator-related logic, primarily providing utility functions like `hasMaxLength` to enforce constraints on facilitator data. It encapsulates core facilitator validation and configuration, serving as a foundational layer for facilitator operations within the application. + +## Boundaries +- **Belongs here:** Utility functions for facilitator data validation (`hasMaxLength`), facilitator configuration constants, and core facilitator logic. +- **Does NOT belong here:** UI rendering, API route handlers, or business logic unrelated to facilitator validation or configuration. Data persistence or external API integrations should reside outside this module. + +## Invariants +- `hasMaxLength(maxLength)` must reliably enforce the maximum length constraint on facilitator input fields; it should throw or return false if violated. +- Facilitator data validation functions must not mutate input data. +- No external dependencies are assumed; all validation logic is self-contained. +- `useFacilitator.ts` should be stable across versions; avoid breaking changes that alter its core contract. +- When modifying `hasMaxLength`, ensure consistent handling of null/undefined inputs—preferably treat them as invalid or empty strings, depending on context. + +## Patterns +- Use clear, descriptive naming: `hasMaxLength` clearly indicates its purpose. +- Validation functions should return boolean; avoid side effects. +- Error handling: if `hasMaxLength` detects violation, it should either throw an explicit error or return false, depending on usage context. +- Maintain immutability: do not mutate input parameters. +- Versioning: track changes to `useFacilitator.ts` and `hasMaxLength` carefully; frequent modifications suggest critical validation logic. + +## Pitfalls +- Be cautious of null/undefined inputs; `hasMaxLength` must handle these gracefully. +- Avoid tight coupling: do not introduce dependencies on external validation libraries unless necessary. +- Beware of frequent churn: changes to `useFacilitator.ts` and `hasMaxLength` are common; document breaking changes thoroughly. +- Do not assume `maxLength` is always positive; validate input parameters. +- When extending `hasMaxLength`, ensure backward compatibility with existing callers. + +## Dependencies +- No external dependencies are directly used; validation logic is self-contained. +- Future enhancements may include integration with form validation libraries or configuration management, but currently, rely solely on internal logic. +- Ensure that any external configuration (if added later) respects the invariants and patterns outlined here. + +--- + +**Note:** Keep modifications minimal and well-documented due to high churn; focus on preserving invariants and following established patterns to prevent regressions. \ No newline at end of file diff --git a/packages/app/server/src/utils/gemini/AGENTS.md b/packages/app/server/src/utils/gemini/AGENTS.md new file mode 100644 index 000000000..44de4b413 --- /dev/null +++ b/packages/app/server/src/utils/gemini/AGENTS.md @@ -0,0 +1,45 @@ +# Gemini String Parsing Utilities + +## Purpose +This module encapsulates string parsing functions used across the application, providing core utilities for interpreting and transforming string data in a consistent manner. It serves as a foundational layer for handling complex string manipulations related to Gemini data formats or protocols. + +## Boundaries +- **Belongs here:** All string parsing logic specific to Gemini data formats; utility functions for string transformations; helper functions for pattern matching within Gemini-related strings. +- **Does NOT belong here:** Business logic unrelated to string parsing; network communication code; data storage or database interactions; UI rendering or presentation logic; external API integrations outside string processing. + +## Invariants +- Parsing functions must handle null, undefined, or malformed input gracefully, returning predictable fallback values or errors. +- String transformations should preserve data integrity; avoid side effects or mutations of input strings. +- Regular expressions or pattern matching used must be consistent and optimized for performance; avoid regex patterns that are overly broad or inefficient. +- Functions should be pure; no external state mutations or side effects. +- When parsing multiple tokens, order of operations must be strictly maintained to ensure correct interpretation. +- Error handling must be explicit; functions should throw or return errors in a way that callers can reliably handle. + +## Patterns +- Use descriptive, camelCase naming conventions for functions (e.g., `parseToken`, `matchPattern`). +- Consistently validate input parameters at the start of each function; return early on invalid data. +- Prefer explicit error returns over silent failures. +- When parsing tokens, always document expected input formats and output structures. +- Use regex patterns that are pre-compiled if reused frequently; avoid recreating regex objects on each call. +- Maintain clear separation between parsing logic and string manipulation utilities. +- Encapsulate complex parsing logic into small, testable functions. +- Document assumptions about input string formats and expected outputs. + +## Pitfalls +- Frequently modified `string-parsing.ts` indicates high churn; modifications may introduce regressions or subtle bugs. +- Overly broad regex patterns can cause performance issues or incorrect parsing. +- Null or undefined inputs are common; neglecting null-safety leads to runtime errors. +- Misordering token parsing steps can produce incorrect results. +- Not handling edge cases (empty strings, malformed tokens) can cause downstream failures. +- Adding new parsing patterns without updating invariants or validation can break existing contracts. +- External callers might assume certain invariants; ensure functions document their contracts explicitly. +- Avoid side effects; functions should be deterministic and stateless. + +## Dependencies +- No external dependencies are used within this module; ensure any future external imports follow the same pattern of explicit, safe usage. +- If integrating with external string libraries or regex utilities, verify they are performant and reliable. +- Maintain awareness of the module's dependency-free status to prevent unintended coupling. + +--- + +**Note:** Given the high churn and frequent modifications, agents should prioritize understanding the evolution history of `string-parsing.ts` to anticipate potential areas of instability or common modification patterns. \ No newline at end of file