OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
ralph(M15-008): R9/R19 + ADR-022 A2/A4: clients become transports - config in, no logger, ProviderError with retryable - and the seven single-consumer clients move into the module that uses them
ralph549628aff4f7
diff --git a/packages/core/src/clients/create-clients.ts b/packages/core/src/clients/create-clients.tsindex b191a55ef..be69f51d2 100644--- a/packages/core/src/clients/create-clients.ts+++ b/packages/core/src/clients/create-clients.ts@@ -7,23 +7,16 @@// exports, gathered so a service can reach an outbound client through its// scoped `Ctx` instead of importing the module directly. Nothing is// constructed here — the geo readers open their mmdb lazily and the email /-// Slack / Discord transports read their own credentials — so building it-// costs one object literal per process.+// Discord transports read their own credentials — so building it costs one+// object literal per process.//-// The modules under `src/modules/**` still import these functions directly.-// Repointing them onto `ctx.clients` is the TECH_DEBT §4 wave (after P9,-// before P12's grep gates); this handle is what that wave repoints ONTO.+// M15-008 removed the `slack` and `ai` members: those transports moved into+// the single module that calls each (ADR-022 A2), and a client handle cannot+// reach up into a module. Nothing read either member.-import { enrichInsights } from './ai/enrich';-import { generateInsightExplanation } from './ai/explain';-import { generateWeeklyNarrative } from './ai/narrative';import { sendEmail } from './email';import { getAsnInfo, getGeoLocation } from './geo';import { sendDiscordNotification } from './integrations/discord';-import {- getSlackInstallUrl,- sendSlackNotification,-} from './integrations/slack';export interface ServiceClients {geo: {@@ -33,30 +26,15 @@ export interface ServiceClients {email: {sendEmail: typeof sendEmail;};- slack: {- sendSlackNotification: typeof sendSlackNotification;- getSlackInstallUrl: typeof getSlackInstallUrl;- };discord: {sendDiscordNotification: typeof sendDiscordNotification;};- ai: {- enrichInsights: typeof enrichInsights;- generateInsightExplanation: typeof generateInsightExplanation;- generateWeeklyNarrative: typeof generateWeeklyNarrative;- };}export function createClients(): ServiceClients {return {geo: { getGeoLocation, getAsnInfo },email: { sendEmail },- slack: { sendSlackNotification, getSlackInstallUrl },discord: { sendDiscordNotification },- ai: {- enrichInsights,- generateInsightExplanation,- generateWeeklyNarrative,- },};}diff --git a/packages/core/src/clients/email.ts b/packages/core/src/clients/email.tsindex fb22488f7..ccb549f25 100644--- a/packages/core/src/clients/email.ts+++ b/packages/core/src/clients/email.ts@@ -7,10 +7,14 @@// depends on @openpanel/core for shared crypto/logging utilities that// haven't moved yet (mid-P4 state). A static top-level import here would// make core's own barrel eagerly load @openpanel/db while core is still-// mid-evaluation — the cycle resolves core's own exports (e.g. createLogger)-// as undefined partway through. Deferring the import to call time sidesteps-// it: by the time anything actually sends an email, core has finished-// loading.+// mid-evaluation — the cycle resolves core's own exports as undefined partway+// through. Deferring the import to call time sidesteps it: by the time+// anything actually sends an email, core has finished loading.+//+// No `ProviderError` (ADR-022 R19): `@openpanel/email` swallows every Resend+// and SMTP failure itself and returns `null`, so nothing reaches this wrapper+// to classify. Classifying it means changing that package, which is outside+// this seam.import type { EmailData, EmailTemplate } from '@openpanel/email';diff --git a/packages/core/src/clients/geo.ts b/packages/core/src/clients/geo.tsindex 57ca12e3a..6744f78db 100644--- a/packages/core/src/clients/geo.ts+++ b/packages/core/src/clients/geo.ts@@ -1,4 +1,11 @@// Ported from @openpanel/geo (dissolved into core — M4-004).+//+// The one client with no `ProviderError` (ADR-022 R19): there is no third+// party on the other end. Both lookups read a bundled MaxMind `.mmdb`, so an+// IP the database does not carry is a missing thing and comes back as the+// default value (R9), and a database that will not load fails identically on+// every retry. `ingest.service.ts` therefore has no failure to classify —+// it reads a value, never a throw.import { readFile } from 'node:fs/promises';import path, { dirname } from 'node:path';diff --git a/packages/core/src/clients/integrations/discord.ts b/packages/core/src/clients/integrations/discord.tsindex e70a0265c..59708add0 100644--- a/packages/core/src/clients/integrations/discord.ts+++ b/packages/core/src/clients/integrations/discord.ts@@ -1,7 +1,6 @@// Ported from @openpanel/integrations (dissolved into core — M4-005).// Cred to (@OpenStatusHQ) https://github.com/openstatusHQ/openstatus/blob/main/packages/notifications/discord/src/index.ts-import { DISCORD_TEST_NOTIFICATION_MESSAGE } from '../../modules/integration/integration.constants';import {browserFetcher,postWebhook,@@ -9,6 +8,12 @@ import {type WebhookResult,} from './fetcher';+// Lives here rather than in integration.constants.ts (ADR-022 A1: a client has+// no need of another module's vocabulary). It is this transport's own probe+// wording, and nothing outside this file reads it.+const DISCORD_TEST_NOTIFICATION_MESSAGE =+ '**🧪 Test [OpenPanel.dev](<https://openpanel.dev/>)**\nIf you can read this, your Discord webhook is functioning correctly!\n';+export function sendDiscordNotification({webhookUrl,message,@@ -17,7 +22,8 @@ export function sendDiscordNotification({webhookUrl: string;message: string;/**- * Server callers MUST pass `safeWebhookFetcher` from `./safe-fetcher` - the+ * Server callers MUST pass `safeWebhookFetcher` from the integration+ * module's `src/safe-fetcher.ts` - the* webhook URL is user-supplied and stored, so sending from inside our network* with a bare `fetch` makes this an SSRF probe.*/diff --git a/packages/core/src/clients/integrations/fetcher.ts b/packages/core/src/clients/integrations/fetcher.tsindex 9a9de69d2..b26c7e662 100644--- a/packages/core/src/clients/integrations/fetcher.ts+++ b/packages/core/src/clients/integrations/fetcher.ts@@ -8,10 +8,13 @@* usable as an SSRF probe.** Injecting the transport keeps this module browser-safe (a plain `fetch`) while- * letting server callers pass the SSRF-guarded one from `./safe-fetcher`, which+ * letting server callers pass the SSRF-guarded one from the integration+ * module's `src/safe-fetcher.ts`, which* pulls in `node:dns`/`undici` and must never reach a client bundle.*/+import { isRetryableStatus } from '../provider-error';+export type WebhookFetcher = (url: string,init: {@@ -21,9 +24,20 @@ export type WebhookFetcher = (}) => Promise<{ status: number }>;+/** No response at all — the request never reached the far end. */+const NO_RESPONSE_STATUS = 0;+export interface WebhookResult {ok: boolean;status: number;+ /**+ * ADR-022 R19, classified once here so no caller re-derives it: 429 and 5xx+ * are worth another delivery attempt, every other 4xx is the destination+ * refusing this exact request. A transport failure that produced no response+ * (DNS, connect, TLS, timeout) is retryable — nothing about the request was+ * rejected.+ */+ retryable: boolean;}export const browserFetcher: WebhookFetcher = async (url, init) => {@@ -47,8 +61,9 @@ export async function postWebhook(body: JSON.stringify(body),});- return { ok: status >= 200 && status < 300, status };+ const ok = status >= 200 && status < 300;+ return { ok, status, retryable: !ok && isRetryableStatus(status) };} catch {- return { ok: false, status: 0 };+ return { ok: false, status: NO_RESPONSE_STATUS, retryable: true };}}diff --git a/packages/core/src/clients/provider-error.test.ts b/packages/core/src/clients/provider-error.test.tsnew file mode 100644index 000000000..9c4f52dbf--- /dev/null+++ b/packages/core/src/clients/provider-error.test.ts@@ -0,0 +1,115 @@+// ADR-022 R19: the classification is the whole point of the type, so the+// boundaries (429 retryable, 4xx not, no status at all) are pinned here rather+// than re-derived by every handler that reads the flag.++import { describe, expect, it } from 'bun:test';+import {+ callProvider,+ isProviderError,+ isRetryableStatus,+ ProviderError,+ providerErrorFrom,+ providerStatusOf,+} from './provider-error';++describe('isRetryableStatus', () => {+ it('treats 429 and 5xx as retryable', () => {+ expect(isRetryableStatus(429)).toBe(true);+ expect(isRetryableStatus(500)).toBe(true);+ expect(isRetryableStatus(503)).toBe(true);+ });++ it('treats every other 4xx as permanent', () => {+ for (const status of [400, 401, 403, 404, 409, 422]) {+ expect(isRetryableStatus(status)).toBe(false);+ }+ });+});++describe('ProviderError', () => {+ it('classifies from the status it was given', () => {+ expect(new ProviderError('slack', 'x', { status: 429 }).retryable).toBe(+ true+ );+ expect(new ProviderError('slack', 'x', { status: 403 }).retryable).toBe(+ false+ );+ });++ it('is retryable with no status — nothing was refused', () => {+ expect(new ProviderError('gcs', 'connect ETIMEDOUT').retryable).toBe(true);+ });++ it('lets an explicit flag override the status classification', () => {+ const error = new ProviderError('gcs', 'bad key', {+ status: 500,+ retryable: false,+ });+ expect(error.retryable).toBe(false);+ });++ it('keeps provider, status and cause for the handler that logs it', () => {+ const cause = new Error('underlying');+ const error = new ProviderError('s3', 'upload failed', {+ status: 503,+ cause,+ });+ expect(error.provider).toBe('s3');+ expect(error.status).toBe(503);+ expect(error.cause).toBe(cause);+ expect(isProviderError(error)).toBe(true);+ expect(isProviderError(cause)).toBe(false);+ });+});++describe('providerStatusOf', () => {+ it('reads the AWS SDK shape', () => {+ expect(providerStatusOf({ $metadata: { httpStatusCode: 403 } })).toBe(403);+ });++ it('reads the Google SDK / fetch-wrapper shapes', () => {+ expect(providerStatusOf({ code: 404 })).toBe(404);+ expect(providerStatusOf({ status: 429 })).toBe(429);+ expect(providerStatusOf({ statusCode: 500 })).toBe(500);+ });++ it('ignores a non-numeric code', () => {+ expect(providerStatusOf({ code: 'ECONNREFUSED' })).toBeUndefined();+ expect(providerStatusOf(new Error('nope'))).toBeUndefined();+ });+});++describe('providerErrorFrom', () => {+ it('classifies an SDK error by its status', () => {+ const wrapped = providerErrorFrom('s3', {+ $metadata: { httpStatusCode: 404 },+ message: 'NoSuchBucket',+ });+ expect(wrapped.retryable).toBe(false);+ expect(wrapped.status).toBe(404);+ });++ it('passes an already-classified error through unchanged', () => {+ const original = new ProviderError('slack', 'x', {+ status: 500,+ retryable: false,+ });+ expect(providerErrorFrom('slack', original)).toBe(original);+ });+});++describe('callProvider', () => {+ it('returns the value when the call succeeds', async () => {+ await expect(callProvider('openai', async () => 'ok')).resolves.toBe('ok');+ });++ it('classifies whatever the call threw', async () => {+ const thrown = await callProvider('openai', () =>+ Promise.reject({ status: 429, message: 'rate limited' })+ ).catch((error: unknown) => error);++ expect(isProviderError(thrown)).toBe(true);+ expect((thrown as ProviderError).retryable).toBe(true);+ expect((thrown as ProviderError).provider).toBe('openai');+ });+});diff --git a/packages/core/src/clients/provider-error.ts b/packages/core/src/clients/provider-error.tsnew file mode 100644index 000000000..6f3eff24d--- /dev/null+++ b/packages/core/src/clients/provider-error.ts@@ -0,0 +1,127 @@+// ADR-022 R19 / A4: the one failure type every outbound client raises.+//+// A client classifies ONCE, at the edge where it still holds the provider's+// own status code; a handler then reads `retryable` instead of re-deriving it+// from a message string. The rule the flag encodes: a retryable failure is+// rethrown so the queue runs the unit of work again, a permanent refusal is+// logged and swallowed, because a retry cannot change it.++/** Too Many Requests — the provider is asking for the same call, later. */+export const RATE_LIMITED_STATUS = 429;++/** The first status in the "the provider is broken, not the request" range. */+const SERVER_ERROR_STATUS_FLOOR = 500;++/**+ * 429 and 5xx are worth another attempt; every other 4xx is the provider+ * refusing THIS request (bad credential, unknown bucket, malformed body) and+ * will refuse it identically next time.+ */+export function isRetryableStatus(status: number): boolean {+ return status === RATE_LIMITED_STATUS || status >= SERVER_ERROR_STATUS_FLOOR;+}++export interface ProviderErrorOptions {+ /** Provider status, when the call got far enough to have one. */+ status?: number;+ /**+ * Overrides the status classification. Only for failures that never reached+ * the provider — DNS, connect, TLS, timeout — where there is no status to+ * read and another attempt genuinely can succeed.+ */+ retryable?: boolean;+ cause?: unknown;+}++/**+ * A third party refused or failed a call. `provider` names the transport+ * ('slack', 'gcs', 'openai') so a log line identifies the hop without the+ * handler knowing which client it called.+ */+export class ProviderError extends Error {+ readonly provider: string;+ readonly retryable: boolean;+ readonly status: number | undefined;++ constructor(+ provider: string,+ message: string,+ options: ProviderErrorOptions = {}+ ) {+ super(message, { cause: options.cause });+ this.name = 'ProviderError';+ this.provider = provider;+ this.status = options.status;+ this.retryable =+ options.retryable ??+ (options.status === undefined ? true : isRetryableStatus(options.status));+ }+}++export function isProviderError(value: unknown): value is ProviderError {+ return value instanceof ProviderError;+}++/**+ * Every SDK we call reports its HTTP status somewhere different: the AWS SDK+ * under `$metadata.httpStatusCode`, the Google SDK and most fetch wrappers as+ * `code`/`status`/`statusCode`. Read all of them here so no client has to.+ */+export function providerStatusOf(error: unknown): number | undefined {+ if (typeof error !== 'object' || error === null) {+ return undefined;+ }+ const candidate = error as {+ status?: unknown;+ statusCode?: unknown;+ code?: unknown;+ $metadata?: { httpStatusCode?: unknown };+ };+ const values = [+ candidate.$metadata?.httpStatusCode,+ candidate.status,+ candidate.statusCode,+ candidate.code,+ ];+ for (const value of values) {+ if (typeof value === 'number' && Number.isFinite(value)) {+ return value;+ }+ }+ return undefined;+}++/**+ * Wrap whatever an SDK threw. A `ProviderError` passes through unchanged —+ * it was already classified by the client that raised it, and reclassifying+ * would throw away the one place that had the provider's own answer.+ */+export function providerErrorFrom(+ provider: string,+ error: unknown,+ message?: string+): ProviderError {+ if (isProviderError(error)) {+ return error;+ }+ const status = providerStatusOf(error);+ const detail =+ message ?? (error instanceof Error ? error.message : String(error));+ return new ProviderError(provider, detail, { status, cause: error });+}++/**+ * Run one outbound call and classify whatever it throws. This is the "classify+ * once" of R19: every `catch` upstream of it can read `retryable` instead of+ * inspecting an SDK-specific error shape.+ */+export async function callProvider<T>(+ provider: string,+ call: () => Promise<T>+): Promise<T> {+ try {+ return await call();+ } catch (error) {+ throw providerErrorFrom(provider, error);+ }+}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 748edfd00..0877a3e74 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -6,9 +6,6 @@// once and mount the three route surfaces plus the tRPC router over it; a// service, a client or a buffer is not reachable from here by design.-// The concrete pino implementation (dissolved from @openpanel/logger,-// M4-003). `./logger` above is the structural interface every module codes-// against; this is what apps/api calls to build one.// The seven buffers (moved from packages/db/src/buffers, M8-001). Only the// FACTORY is on the barrel: they are boot singletons on `AppDeps`, built once// by `main.ts`, never module singletons (ADR-007). V1's@@ -31,109 +28,22 @@ export type { ProfileBackfillEntry } from './buffers/profile-backfill-buffer';export type { IClickhouseSessionReplayChunk } from './buffers/replay-buffer';export type { SessionIngestResult } from './buffers/session-buffer';export { resolveSessionTimeoutMs } from './buffers/session-buffer';-// Dissolved from @openpanel/ai (M4-005) — the chat agent app, the filter-// command bar, insight explanation/enrichment and the worker's digest and-// win-back emails all call these directly.-export type {- InsightCategory,- InsightEnrichment,- InsightToEnrich,-} from './clients/ai/enrich';-export { ENRICH_VERSION, enrichInsights } from './clients/ai/enrich';-export type {- BreakdownComparison,- DailyPoint,- ExplainInsightInput,- InsightExplanation,-} from './clients/ai/explain';-export { generateInsightExplanation } from './clients/ai/explain';-export type { WeeklyNarrativeInput } from './clients/ai/narrative';-export { generateWeeklyNarrative } from './clients/ai/narrative';-export type { ChatModelEntry } from './clients/ai/providers';-export {- ALLOWED_MODELS,- anthropicProvider,- openaiProvider,- resolveModel,-} from './clients/ai/providers';-export type { WinBackPitchInput } from './clients/ai/win-back';-export { generateWinBackPitch } from './clients/ai/win-back';-// The `clients` handle on AppDeps (M9-004). main.ts builds it once and hands-// it to `AppDeps`, the same way it builds the buffers and the producers.+// ADR-022 R13, M15-008: of the ~35 `clients/` symbols this barrel used to+// re-export, `main.ts` imported one (`createClients`) and `apps/start` none.+// The rest — every AI call, the Slack/Discord senders, the geo lookups, the+// object-store adapters, the integration registry — are reached by relative+// import inside this package and are no longer on the public surface.+// `pino-logger` is the concrete implementation of `./logger`'s structural+// interface; main.ts builds its own named logger from it and mirrors a fatal+// to the real stderr with the write captured before `interceptProcessOutput`+// wrapped the stream.export type { ServiceClients } from './clients/create-clients';export { createClients } from './clients/create-clients';-export type { EmailData, EmailTemplate } from './clients/email';-export { sendEmail } from './clients/email';-// Dissolved from @openpanel/geo (M4-004) — apps/api's ingest and tools-// controllers call these directly, the same way they reach the logger below.-export type { AsnInfo, GeoLocation } from './clients/geo';-export { getAsnInfo, getGeoLocation } from './clients/geo';-// Dissolved from @openpanel/integrations (M4-005) — the export cron job, the-// notification worker job and the Slack/webhook OAuth callback all reach-// these directly, the same way they reach the object-store adapters below.-export {- sendDiscordNotification,- sendTestDiscordNotification,-} from './clients/integrations/discord';-export {- clickhouseEventToExportEvent,- createBatch,- createManifest,- EXPORT_SCHEMA_VERSION,- type ExportFormat,- generateBatchPath,- getContentType,- getFileExtension,- type IBatchFile,- type IBatchInfo,- type IBatchResult,- type IExportEvent,- type IManifest,- MANIFEST_CONTENT_TYPE,- MANIFEST_FILENAME,- parseManifest,- serializeManifest,-} from './clients/integrations/export';-export type {- IObjectStoreAdapter,- IUploadOptions,- IUploadResult,-} from './clients/integrations/object-store';export {- createGCSAdapter,- createS3Adapter,- GCSAdapter,- S3Adapter,-} from './clients/integrations/object-store';-export type {- ConfigOf,- IConfigSecret,- INotificationDeliverArgs,- INotificationDeliverPayload,- IServerIntegration,-} from './clients/integrations/registry';-export {- carryOverConfigSecrets,- encryptConfigSecrets,- findEncryptedSecretField,- findMissingSecretFields,- getServerIntegration,- redactConfigSecrets,-} from './clients/integrations/registry';-export { safeWebhookFetcher } from './clients/integrations/safe-fetcher';-export {- getSlackInstallUrl,- sendSlackNotification,- slackInstaller,-} from './clients/integrations/slack';-export type { ILogger } from './clients/logger';-export {- createLogger,- getServiceName,- interceptProcessOutput,- rawStderrWrite,- rawStdoutWrite,-} from './clients/logger';+ isRetryableStatus,+ ProviderError,+ type ProviderErrorOptions,+} from './clients/provider-error';export type {AppDeps,CoreConfig,@@ -951,6 +861,14 @@ export { runSiteCheck } from './modules/tools/src/site-checker';// `getUserAccount` directly through @openpanel/db's re-export shim, the same// way they reach every other dissolved service here.export { createUserService } from './modules/user/user.service';+export type { ILogger } from './pino-logger';+export {+ createLogger,+ getServiceName,+ interceptProcessOutput,+ rawStderrWrite,+ rawStdoutWrite,+} from './pino-logger';export { dashboardRoutes, opsRoutes, publicApiRoutes } from './rest.routes';// The RPC base is on the barrel because it is the seam every module's own// `<name>.rpc.ts` builds its router on: ONE tRPC instance (ADR-009), mounteddiff --git a/packages/core/src/modules/assistant/src/app.ts b/packages/core/src/modules/assistant/src/app.tsindex 9f305672a..d89accc1e 100644--- a/packages/core/src/modules/assistant/src/app.ts+++ b/packages/core/src/modules/assistant/src/app.ts@@ -8,16 +8,16 @@// `@better-agent/core`'s context-free tool-handler signature ruled out doing// as an argument.import { betterAgent, defineAgent } from '@better-agent/core';+import type { ServiceDeps } from '../../../services';+import { type ChatAgentContext, chatContextSchema } from './context';+import { createConversationStore } from './persistence';+import { buildSystemPrompt } from './prompt';import {ALLOWED_MODELS,type ChatModelEntry,openaiProvider,resolveModel,-} from '../../../clients/ai/providers';-import type { ServiceDeps } from '../../../services';-import { type ChatAgentContext, chatContextSchema } from './context';-import { createConversationStore } from './persistence';-import { buildSystemPrompt } from './prompt';+} from './providers';import { composeChatTools } from './tools';/**diff --git a/packages/core/src/modules/assistant/src/filter-command.ts b/packages/core/src/modules/assistant/src/filter-command.tsindex 44c6ba8c4..c10a6d0f6 100644--- a/packages/core/src/modules/assistant/src/filter-command.ts+++ b/packages/core/src/modules/assistant/src/filter-command.ts@@ -14,7 +14,6 @@ import {type ToolRunContext,} from '@better-agent/core';import { z } from 'zod';-import { resolveModel } from '../../../clients/ai/providers';import type { CoreConfig } from '../../../config';import type { ServiceDeps } from '../../../services';import {@@ -37,6 +36,7 @@ import {type ChatModelEntry,type PageContext,} from '../assistant.constants';+import { resolveModel } from './providers';// Helper, not vocabulary — ADR-008's ruling on objectToZodEnums: copy locally// rather than import from a module.diff --git a/packages/core/src/clients/ai/providers.ts b/packages/core/src/modules/assistant/src/providers.tssimilarity index 81%rename from packages/core/src/clients/ai/providers.tsrename to packages/core/src/modules/assistant/src/providers.tsindex fc50ca407..a8f999694 100644--- a/packages/core/src/clients/ai/providers.ts+++ b/packages/core/src/modules/assistant/src/providers.ts@@ -1,4 +1,7 @@-// Ported from @openpanel/ai (dissolved into core — M4-005).+// Ported from @openpanel/ai (dissolved into core — M4-005). Moved out of+// `clients/ai/` by M15-008: the assistant is its only consumer, so ADR-022 A2+// puts it in this module's `src/` — which is also what removes its upward+// edge onto `assistant.constants`.//// SERVER-ONLY. This module instantiates `@better-agent/providers` clients from// the credentials the config loader parsed (ADR-022 R9: config in). Never@@ -7,11 +10,11 @@// `@openpanel/core/modules/assistant/assistant.constants` instead.import { createAnthropic } from '@better-agent/providers/anthropic';import { createOpenAI } from '@better-agent/providers/openai';-import type { CoreConfig } from '../../config';-import type { ChatModelEntry } from '../../modules/assistant/assistant.constants';+import type { CoreConfig } from '../../../config';+import type { ChatModelEntry } from '../assistant.constants';-export type { ChatModelEntry } from '../../modules/assistant/assistant.constants';-export { CHAT_MODELS as ALLOWED_MODELS } from '../../modules/assistant/assistant.constants';+export type { ChatModelEntry } from '../assistant.constants';+export { CHAT_MODELS as ALLOWED_MODELS } from '../assistant.constants';// One provider client per process, built on first use. The credentials are// the same object for every caller — `loadConfig` runs once at boot — so thediff --git a/packages/core/src/modules/ingest/src/kafka.ts b/packages/core/src/modules/ingest/src/kafka.tsindex 4fd0a51a5..01bd14cd0 100644--- a/packages/core/src/modules/ingest/src/kafka.ts+++ b/packages/core/src/modules/ingest/src/kafka.ts@@ -19,8 +19,8 @@ import {logLevel,type Producer,} from 'kafkajs';-import { createLogger, type ILogger } from '../../../clients/logger';import type { CoreConfig, KafkaConfig } from '../../../config';+import { createLogger, type ILogger } from '../../../pino-logger';// One definition, not two: the consumer already declares the dead-letter// message shape it hands to this producer, and both files are now siblings.import type { DeadLetterMessage } from './consumer';diff --git a/packages/core/src/modules/insight/insight.service.test.ts b/packages/core/src/modules/insight/insight.service.test.tsindex aeea7f377..af40b85fb 100644--- a/packages/core/src/modules/insight/insight.service.test.ts+++ b/packages/core/src/modules/insight/insight.service.test.ts@@ -53,7 +53,7 @@ const generateInsightExplanation = mock(async () => ({relatedReference: '',confidence: 'low' as const,}));-mock.module('../../clients/ai/explain', () => ({+mock.module('./src/explain', () => ({generateInsightExplanation,}));diff --git a/packages/core/src/modules/insight/insight.service.ts b/packages/core/src/modules/insight/insight.service.tsindex f382aa0a7..4e37f9a78 100644--- a/packages/core/src/modules/insight/insight.service.ts+++ b/packages/core/src/modules/insight/insight.service.ts@@ -21,22 +21,22 @@// `legacy-scan.ts` is the last clix holdout in this module (M12-008).import { getRedisCache } from '@openpanel/redis';+import { sendEmail } from '../../clients/email';+import type { Logger } from '../../logger';+import type { ServiceDeps, Services } from '../../services';+import type { EngineConfig } from './src/engine';import {ENRICH_VERSION,enrichInsights,type InsightToEnrich,-} from '../../clients/ai/enrich';+} from './src/enrich';import {type ExplainInsightInput,generateInsightExplanation,type InsightExplanation,-} from '../../clients/ai/explain';-import { generateWeeklyNarrative } from '../../clients/ai/narrative';-import { sendEmail } from '../../clients/email';-import type { Logger } from '../../logger';-import type { ServiceDeps, Services } from '../../services';-import type { EngineConfig } from './src/engine';+} from './src/explain';import type { Insight as LegacyInsight } from './src/legacy-scan';+import { generateWeeklyNarrative } from './src/narrative';import type {GetReferrerSpikesInput,ReferrerSpikeCluster,@@ -698,7 +698,7 @@ export async function scanLegacyInsights(export type {ExplainInsightInput,InsightExplanation,-} from '../../clients/ai/explain';+} from './src/explain';export type {GetReferrerSpikesInput,ReferrerSpikeCluster,diff --git a/packages/core/src/clients/ai/enrich.ts b/packages/core/src/modules/insight/src/enrich.tssimilarity index 88%rename from packages/core/src/clients/ai/enrich.tsrename to packages/core/src/modules/insight/src/enrich.tsindex 401724612..1dd1f1b23 100644--- a/packages/core/src/clients/ai/enrich.ts+++ b/packages/core/src/modules/insight/src/enrich.ts@@ -7,8 +7,9 @@// writes the results back (this module stays db-free).import { betterAgent, defineAgent } from '@better-agent/core';import { z } from 'zod';-import type { CoreConfig } from '../../config';-import { ALLOWED_MODELS, resolveModel } from './providers';+import { callProvider } from '../../../clients/provider-error';+import type { CoreConfig } from '../../../config';+import { ALLOWED_MODELS, resolveModel } from '../../assistant/src/providers';// Bump when the prompt or output shape changes — the worker re-enriches any// insight whose stored enrichVersion is below this.@@ -17,6 +18,10 @@ export const ENRICH_VERSION = 1;// Tier-1 is cheap, fast, non-reasoning work — gpt-4.1-mini is the right tier.const ENRICH_MODEL_ID = 'gpt-4-1-mini';+// Both the preferred model and the fallback are OpenAI, so every failure this+// call classifies is an OpenAI one.+const ENRICH_PROVIDER = 'openai';+function enrichModel(config: CoreConfig) {const entry =ALLOWED_MODELS.find((m) => m.id === ENRICH_MODEL_ID) ??@@ -123,11 +128,13 @@ export async function enrichInsights(}const input = JSON.stringify(insights);- const result = (await getApp(config).run('insight-enrich', {- input,- context: {},- // biome-ignore lint/suspicious/noExplicitAny: same dodge as filter-command.ts- } as any)) as { structured?: { results: InsightEnrichment[] } };+ const result = (await callProvider(ENRICH_PROVIDER, () =>+ getApp(config).run('insight-enrich', {+ input,+ context: {},+ // biome-ignore lint/suspicious/noExplicitAny: same dodge as filter-command.ts+ } as any)+ )) as { structured?: { results: InsightEnrichment[] } };return result.structured?.results ?? [];}diff --git a/packages/core/src/clients/ai/explain.ts b/packages/core/src/modules/insight/src/explain.tssimilarity index 90%rename from packages/core/src/clients/ai/explain.tsrename to packages/core/src/modules/insight/src/explain.tsindex 5985fe307..f5133907d 100644--- a/packages/core/src/clients/ai/explain.ts+++ b/packages/core/src/modules/insight/src/explain.ts@@ -8,14 +8,18 @@// causes. The caller gathers the data (DB/CH); this module just narrates.import { betterAgent, defineAgent } from '@better-agent/core';import { z } from 'zod';-import type { CoreConfig } from '../../config';-import { ALLOWED_MODELS, resolveModel } from './providers';+import { callProvider } from '../../../clients/provider-error';+import type { CoreConfig } from '../../../config';+import { ALLOWED_MODELS, resolveModel } from '../../assistant/src/providers';// gpt-4.1 (the larger non-reasoning model) synthesizes the supplied breakdown// well without reasoning-option plumbing. Swap to a reasoning model later if// deeper inference is wanted.const EXPLAIN_MODEL_ID = 'gpt-4-1';+// Preferred model and fallback are both OpenAI — see enrich.ts.+const EXPLAIN_PROVIDER = 'openai';+function explainModel(config: CoreConfig) {const entry =ALLOWED_MODELS.find((m) => m.id === EXPLAIN_MODEL_ID) ??@@ -127,11 +131,13 @@ export async function generateInsightExplanation(config: CoreConfig,input: ExplainInsightInput): Promise<InsightExplanation | null> {- const result = (await getApp(config).run('insight-explain', {- input: JSON.stringify(input),- context: {},- // biome-ignore lint/suspicious/noExplicitAny: same dodge as enrich.ts- } as any)) as { structured?: InsightExplanation };+ const result = (await callProvider(EXPLAIN_PROVIDER, () =>+ getApp(config).run('insight-explain', {+ input: JSON.stringify(input),+ context: {},+ // biome-ignore lint/suspicious/noExplicitAny: same dodge as enrich.ts+ } as any)+ )) as { structured?: InsightExplanation };return result.structured ?? null;}diff --git a/packages/core/src/clients/ai/narrative.ts b/packages/core/src/modules/insight/src/narrative.tssimilarity index 81%rename from packages/core/src/clients/ai/narrative.tsrename to packages/core/src/modules/insight/src/narrative.tsindex 8bf4f2146..46b352be6 100644--- a/packages/core/src/clients/ai/narrative.ts+++ b/packages/core/src/modules/insight/src/narrative.ts@@ -6,11 +6,15 @@// pattern as enrich.ts / filter-command.ts.import { betterAgent, defineAgent } from '@better-agent/core';import { z } from 'zod';-import type { CoreConfig } from '../../config';-import { ALLOWED_MODELS, resolveModel } from './providers';+import { callProvider } from '../../../clients/provider-error';+import type { CoreConfig } from '../../../config';+import { ALLOWED_MODELS, resolveModel } from '../../assistant/src/providers';const NARRATIVE_MODEL_ID = 'gpt-4-1-mini';+// Preferred model and fallback are both OpenAI — see enrich.ts.+const NARRATIVE_PROVIDER = 'openai';+function narrativeModel(config: CoreConfig) {const entry =ALLOWED_MODELS.find((m) => m.id === NARRATIVE_MODEL_ID) ??@@ -77,11 +81,13 @@ export async function generateWeeklyNarrative(config: CoreConfig,input: WeeklyNarrativeInput): Promise<string> {- const result = (await getApp(config).run('weekly-narrative', {- input: JSON.stringify(input),- context: {},- // biome-ignore lint/suspicious/noExplicitAny: same dodge as enrich.ts- } as any)) as { structured?: { narrative: string } };+ const result = (await callProvider(NARRATIVE_PROVIDER, () =>+ getApp(config).run('weekly-narrative', {+ input: JSON.stringify(input),+ context: {},+ // biome-ignore lint/suspicious/noExplicitAny: same dodge as enrich.ts+ } as any)+ )) as { structured?: { narrative: string } };return result.structured?.narrative ?? '';}diff --git a/packages/core/src/modules/integration/integration.constants.ts b/packages/core/src/modules/integration/integration.constants.tsindex 0194e0b34..055175d6c 100644--- a/packages/core/src/modules/integration/integration.constants.ts+++ b/packages/core/src/modules/integration/integration.constants.ts@@ -273,7 +273,7 @@ export type IIntegrationType = IIntegrationConfig['type'];// ---------------------------------------------------------------------------// Plugin descriptor registry (core layer). Each integration declares its// capabilities, setup style, config schema and catalog metadata once. The-// server (@openpanel/core's clients/integrations/registry.ts) and client+// server (this module's src/registry.ts) and client// (apps/start) registries are keyed by the same `type` literal and are// forced to cover this union.// ---------------------------------------------------------------------------@@ -482,13 +482,3 @@ type _DescriptorTypes = (typeof INTEGRATION_DESCRIPTORS)[number]['type'];type _AssertDescriptorCoverage = Assert<Equal<IIntegrationType, _DescriptorTypes>>;--// ----------------------------------------------------------------------------// Discord test-notification wording (previously hardcoded in-// clients/integrations/discord.ts's `sendTestDiscordNotification` as a-// copy-pasted Slack message — "your Slack webhook is functioning correctly!"-// on a Discord test send). Named and fixed here per the module map.-// -----------------------------------------------------------------------------export const DISCORD_TEST_NOTIFICATION_MESSAGE =- '**🧪 Test [OpenPanel.dev](<https://openpanel.dev/>)**\nIf you can read this, your Discord webhook is functioning correctly!\n';diff --git a/packages/core/src/modules/integration/integration.jobs.ts b/packages/core/src/modules/integration/integration.jobs.tsindex fd6a56043..fea8ef9a8 100644--- a/packages/core/src/modules/integration/integration.jobs.ts+++ b/packages/core/src/modules/integration/integration.jobs.ts@@ -26,9 +26,7 @@ export const integrationCronJobs = {// Lazy: the registry pulls the S3 and GCS SDKs, ~270ms of module// evaluation (measured, Bun 1.4.0) that a static edge here would add to// jobs.registry.ts's eager graph and so to every core test file.- const { getServerIntegration } = await import(- '../../clients/integrations/registry'- );+ const { getServerIntegration } = await import('./src/registry');await runFlushExportsCron({db: ctx.db as unknown as ExportDb,diff --git a/packages/core/src/modules/integration/integration.service.ts b/packages/core/src/modules/integration/integration.service.tsindex be604e8f4..ea8dcd831 100644--- a/packages/core/src/modules/integration/integration.service.ts+++ b/packages/core/src/modules/integration/integration.service.ts@@ -22,6 +22,12 @@// the edge reaches the query (ADR-018, docs/TECH_DEBT.md §4).import { z } from 'zod';+import { TRPCBadRequestError, TRPCForbiddenError } from '../../rpc/errors';+import type { ServiceDeps, Services } from '../../services';+import { getOrganizationAccess } from '../../shared/access-lookups';+import { getAccessChecks } from '../auth/auth.service';+import { BASE_INTEGRATIONS } from '../notification/notification.service';+import type { IIntegrationConfig, ISlackConfig } from './integration.constants';import {carryOverConfigSecrets,encryptConfigSecrets,@@ -29,19 +35,13 @@ import {findMissingSecretFields,getServerIntegration,redactConfigSecrets,-} from '../../clients/integrations/registry';-import { safeWebhookFetcher } from '../../clients/integrations/safe-fetcher';+} from './src/registry';+import { safeWebhookFetcher } from './src/safe-fetcher';import {getSlackInstallUrl,sendSlackNotification,slackInstaller,-} from '../../clients/integrations/slack';-import { TRPCBadRequestError, TRPCForbiddenError } from '../../rpc/errors';-import type { ServiceDeps, Services } from '../../services';-import { getOrganizationAccess } from '../../shared/access-lookups';-import { getAccessChecks } from '../auth/auth.service';-import { BASE_INTEGRATIONS } from '../notification/notification.service';-import type { IIntegrationConfig, ISlackConfig } from './integration.constants';+} from './src/slack';import { zSlackAuthResponse } from './src/slack-contract';// Credentials are write-only: they are encrypted at rest and never travel back@@ -315,15 +315,23 @@ export async function createOrUpdateSlackIntegration(},});- return {- ...res,- slackInstallUrl: await getSlackInstallUrl({- config: deps.config,- integrationId: res.id,- organizationId,- projectId,- }),- };+ // `getSlackInstallUrl` returns null when no Slack app is configured on this+ // deployment (ADR-022 R9: the client reports a missing thing as null). The+ // decision that a Slack integration is unusable without one is this+ // service's, not the transport's.+ const installUrl = await getSlackInstallUrl({+ config: deps.config,+ integrationId: res.id,+ organizationId,+ projectId,+ });+ if (!installUrl) {+ throw new TRPCBadRequestError(+ 'Slack is not configured on this OpenPanel deployment'+ );+ }++ return { ...res, slackInstallUrl: installUrl };}// Generic, registry-driven connection test. Gated on project write access:diff --git a/packages/core/src/clients/integrations/export/batch-creator.ts b/packages/core/src/modules/integration/src/export/batch-creator.tssimilarity index 97%rename from packages/core/src/clients/integrations/export/batch-creator.tsrename to packages/core/src/modules/integration/src/export/batch-creator.tsindex 122da8d5e..3cd742cc7 100644--- a/packages/core/src/clients/integrations/export/batch-creator.ts+++ b/packages/core/src/modules/integration/src/export/batch-creator.ts@@ -1,8 +1,8 @@import { Readable } from 'node:stream';import { pipeline } from 'node:stream/promises';import { createGzip } from 'node:zlib';-import type { Logger } from '../../../logger';-import { generateSecureId } from '../../../shared/id';+import type { Logger } from '../../../../logger';+import { generateSecureId } from '../../../../shared/id';import type { IExportEvent } from './export-event';/**diff --git a/packages/core/src/clients/integrations/export/export-event.ts b/packages/core/src/modules/integration/src/export/export-event.tssimilarity index 96%rename from packages/core/src/clients/integrations/export/export-event.tsrename to packages/core/src/modules/integration/src/export/export-event.tsindex 822539573..6537174e3 100644--- a/packages/core/src/clients/integrations/export/export-event.ts+++ b/packages/core/src/modules/integration/src/export/export-event.ts@@ -1,4 +1,4 @@-import type { IClickhouseEvent } from '../../../modules/event/event.service';+import type { IClickhouseEvent } from '../../../event/event.service';// Local copy for the reason every modules/*/src/dates.ts gives: importing// @openpanel/db's clickhouse/client constructs a ClickHouse client at importdiff --git a/packages/core/src/clients/integrations/export/index.ts b/packages/core/src/modules/integration/src/export/index.tssimilarity index 100%rename from packages/core/src/clients/integrations/export/index.tsrename to packages/core/src/modules/integration/src/export/index.tsdiff --git a/packages/core/src/clients/integrations/export/manifest.ts b/packages/core/src/modules/integration/src/export/manifest.tssimilarity index 100%rename from packages/core/src/clients/integrations/export/manifest.tsrename to packages/core/src/modules/integration/src/export/manifest.tsdiff --git a/packages/core/src/modules/integration/src/flush-exports.test.ts b/packages/core/src/modules/integration/src/flush-exports.test.tsindex 5ad70b937..05ffb323f 100644--- a/packages/core/src/modules/integration/src/flush-exports.test.ts+++ b/packages/core/src/modules/integration/src/flush-exports.test.ts@@ -6,6 +6,7 @@import { describe, expect, it, mock } from 'bun:test';import { gunzipSync } from 'node:zlib';import { testCoreConfig } from '../../../../test/config-fixture';+import type { Logger } from '../../../logger';import {clickhouseEventToExportEvent,createBatch,@@ -15,15 +16,14 @@ import {MANIFEST_FILENAME,parseManifest,serializeManifest,-} from '../../../clients/integrations/export';-import { createGCSAdapter } from '../../../clients/integrations/object-store/gcs-adapter';-import type { Logger } from '../../../logger';+} from './export';import {type ExportIntegrationRow,type ExportWatermarkRow,type FlushExportsDeps,runFlushExportsCron,} from './flush-exports';+import { createGCSAdapter } from './object-store/gcs-adapter';function stubLogger(): Logger {const noop = () => undefined;@@ -167,7 +167,7 @@ describe('runFlushExportsCron', () => {/*** Exercises the object-store export path end to end against a local- * fake-gcs-server (see clients/integrations/object-store/gcs-adapter.test.ts+ * fake-gcs-server (see ./object-store/gcs-adapter.test.ts* for how to start it). The job's own ClickHouse/Postgres I/O is out of scope* here; what this pins down is the part a consumer depends on — batch files* land, then a manifest that points at them, under the partitioned path.diff --git a/packages/core/src/modules/integration/src/flush-exports.ts b/packages/core/src/modules/integration/src/flush-exports.tsindex cf1cb0d38..7d5c6ee79 100644--- a/packages/core/src/modules/integration/src/flush-exports.ts+++ b/packages/core/src/modules/integration/src/flush-exports.ts@@ -9,16 +9,7 @@// value through ClickHouse's own `{name:Type}` params, and converting it to the// `sql` tag would change the emitted statement. Kept byte-identical.-import {- clickhouseEventToExportEvent,- createBatch,- createManifest,- generateBatchPath,- MANIFEST_CONTENT_TYPE,- MANIFEST_FILENAME,- serializeManifest,-} from '../../../clients/integrations/export';-import type { IObjectStoreAdapter } from '../../../clients/integrations/object-store';+import { isProviderError } from '../../../clients/provider-error';import type { CoreConfig } from '../../../config';import type { Logger } from '../../../logger';import { DateTime } from '../../../shared/date';@@ -29,6 +20,16 @@ import {type IS3ExportConfig,isKind,} from '../integration.constants';+import {+ clickhouseEventToExportEvent,+ createBatch,+ createManifest,+ generateBatchPath,+ MANIFEST_CONTENT_TYPE,+ MANIFEST_FILENAME,+ serializeManifest,+} from './export';+import type { IObjectStoreAdapter } from './object-store';// Safety lag: never export events whose inserted_at is within this window of// now(), so an in-flight CH insert batch (or replica lag) can't be half-read at@@ -172,6 +173,11 @@ export async function runFlushExportsCron(}}+ // ADR-022 R19: the adapters classify, this reads the flag. A permanent+ // refusal (bad bucket, revoked key) is logged and left alone — the next tick+ // would refuse identically. A retryable one fails the job at the end, so a+ // provider outage is visible rather than a green run that exported nothing.+ let retryableFailures = 0;await runWithConcurrency(items,deps.config.objectStoreExport.concurrency ?? DEFAULT_CONCURRENCY,@@ -182,16 +188,27 @@ export async function runFlushExportsCron(item.config,deps).catch((error) => {+ const retryable = !isProviderError(error) || error.retryable;+ if (retryable) {+ retryableFailures++;+ }deps.logger.error({err: error,projectId: item.projectId,integrationId: item.integrationId,+ retryable,},'Export failed for project');}));++ if (retryableFailures > 0) {+ throw new Error(+ `${retryableFailures} of ${items.length} exports failed with a retryable provider error`+ );+ }}async function processExport(diff --git a/packages/core/src/clients/integrations/object-store/gcs-adapter.test.ts b/packages/core/src/modules/integration/src/object-store/gcs-adapter.test.tssimilarity index 98%rename from packages/core/src/clients/integrations/object-store/gcs-adapter.test.tsrename to packages/core/src/modules/integration/src/object-store/gcs-adapter.test.tsindex 614c32eb0..894d37c7b 100644--- a/packages/core/src/clients/integrations/object-store/gcs-adapter.test.ts+++ b/packages/core/src/modules/integration/src/object-store/gcs-adapter.test.ts@@ -1,7 +1,7 @@import { beforeAll, describe, expect, it } from 'bun:test';import { gunzipSync, gzipSync } from 'node:zlib';-import { testCoreConfig } from '../../../../test/config-fixture';-import { encryptCredential } from '../../../shared/encryption';+import { testCoreConfig } from '../../../../../test/config-fixture';+import { encryptCredential } from '../../../../shared/encryption';import { createGCSAdapter } from './gcs-adapter';/**diff --git a/packages/core/src/clients/integrations/object-store/gcs-adapter.ts b/packages/core/src/modules/integration/src/object-store/gcs-adapter.tssimilarity index 75%rename from packages/core/src/clients/integrations/object-store/gcs-adapter.tsrename to packages/core/src/modules/integration/src/object-store/gcs-adapter.tsindex 8c7ecf869..f8b70c2c3 100644--- a/packages/core/src/clients/integrations/object-store/gcs-adapter.ts+++ b/packages/core/src/modules/integration/src/object-store/gcs-adapter.ts@@ -1,26 +1,26 @@// Ported from @openpanel/integrations (dissolved into core — M4-005).import { Storage } from '@google-cloud/storage';-import type { CoreConfig } from '../../../config';+import {+ callProvider,+ ProviderError,+} from '../../../../clients/provider-error';+import type { CoreConfig } from '../../../../config';+import { decryptCredential } from '../../../../shared/encryption';import {type IGCSExportConfig,parseServiceAccountKey,-} from '../../../modules/integration/integration.constants';-import { decryptCredential } from '../../../shared/encryption';-import { createLogger, type ILogger } from '../../logger';+} from '../../integration.constants';import type {IObjectStoreAdapter,IUploadOptions,IUploadResult,} from './types';-// Lazy: constructing a pino logger spins up a worker thread for the-// pino-pretty transport, so a module that is merely imported (every test file-// that reaches the object-store barrel) must not pay for one unused.-let _logger: ILogger | null = null;-function logger(coreConfig: CoreConfig): ILogger {- _logger ??= createLogger({ name: 'gcs-adapter', config: coreConfig });- return _logger;-}+/** ADR-022 R19: every failure that leaves this adapter is classified as this. */+const GCS_PROVIDER = 'gcs';++// A credential this adapter refuses is a refusal no retry can change.+const CREDENTIAL_REJECTED_RETRYABLE = false;/** Object written by `testConnection`; named so it is obvious in a bucket. */const CONNECTION_TEST_FILENAME = '.openpanel-connection-test';@@ -69,11 +69,11 @@ export class GCSAdapter implements IObjectStoreAdapter {// any future caller that skips it.const parsed = parseServiceAccountKey(this.config.serviceAccountKey);if (!parsed.ok) {- logger(this.coreConfig).error(- { reason: parsed.error },- 'Rejected GCS credential document'+ throw new ProviderError(+ GCS_PROVIDER,+ `Invalid service account key: ${parsed.error}`,+ { retryable: CREDENTIAL_REJECTED_RETRYABLE });- throw new Error(`Invalid service account key: ${parsed.error}`);}const { credentials } = parsed;@@ -106,17 +106,12 @@ export class GCSAdapter implements IObjectStoreAdapter {...(apiEndpoint ? { apiEndpoint } : {}),});- logger(this.coreConfig).debug(- {- projectId: credentials.project_id,- },- 'GCS client created'- );-return this.storage;} catch (error) {- logger(this.coreConfig).error({ error }, 'Failed to create GCS client');- throw new Error('Failed to create GCS client');+ throw new ProviderError(GCS_PROVIDER, 'Failed to create GCS client', {+ retryable: CREDENTIAL_REJECTED_RETRYABLE,+ cause: error,+ });}}@@ -128,50 +123,31 @@ export class GCSAdapter implements IObjectStoreAdapter {const bucket = storage.bucket(options.bucket);const file = bucket.file(options.key);- try {- const content =- typeof options.content === 'string'- ? Buffer.from(options.content)- : options.content;+ const content =+ typeof options.content === 'string'+ ? Buffer.from(options.content)+ : options.content;- await file.save(content, {+ await callProvider(GCS_PROVIDER, () =>+ file.save(content, {contentType: options.contentType,resumable: false, // For small files, non-resumable is fastermetadata: {contentType: options.contentType,},- });+ })+ );- // `save` populates `file.metadata` from the upload response, so re-reading- // it with getMetadata() would double the request count of every export.- const metadata = file.metadata;+ // `save` populates `file.metadata` from the upload response, so re-reading+ // it with getMetadata() would double the request count of every export.+ const metadata = file.metadata;- logger(this.coreConfig).debug(- {- bucket: options.bucket,- key: options.key,- generation: metadata?.generation,- },- 'File uploaded to GCS'- );-- return {- bucket: options.bucket,- key: options.key,- etag: metadata?.etag || undefined,- location: `gs://${options.bucket}/${options.key}`,- };- } catch (error) {- logger(this.coreConfig).error(- {- error,- bucket: options.bucket,- key: options.key,- },- 'Failed to upload file to GCS'- );- throw error;- }+ return {+ bucket: options.bucket,+ key: options.key,+ etag: metadata?.etag || undefined,+ location: `gs://${options.bucket}/${options.key}`,+ };}/**diff --git a/packages/core/src/clients/integrations/object-store/index.ts b/packages/core/src/modules/integration/src/object-store/index.tssimilarity index 100%rename from packages/core/src/clients/integrations/object-store/index.tsrename to packages/core/src/modules/integration/src/object-store/index.tsdiff --git a/packages/core/src/clients/integrations/object-store/s3-adapter.ts b/packages/core/src/modules/integration/src/object-store/s3-adapter.tssimilarity index 80%rename from packages/core/src/clients/integrations/object-store/s3-adapter.tsrename to packages/core/src/modules/integration/src/object-store/s3-adapter.tsindex 1f2a5abb4..9d1cbaf26 100644--- a/packages/core/src/clients/integrations/object-store/s3-adapter.ts+++ b/packages/core/src/modules/integration/src/object-store/s3-adapter.ts@@ -9,25 +9,26 @@ import {S3Client,} from '@aws-sdk/client-s3';import { AssumeRoleCommand, STSClient } from '@aws-sdk/client-sts';-import type { CoreConfig } from '../../../config';-import type { IS3ExportConfig } from '../../../modules/integration/integration.constants';-import { decryptCredential } from '../../../shared/encryption';-import { assertSafeUrl, createPinnedLookup } from '../../../shared/ssrf';-import { createLogger, type ILogger } from '../../logger';+import {+ callProvider,+ ProviderError,+ providerErrorFrom,+} from '../../../../clients/provider-error';+import type { CoreConfig } from '../../../../config';+import { decryptCredential } from '../../../../shared/encryption';+import { assertSafeUrl, createPinnedLookup } from '../../../../shared/ssrf';+import type { IS3ExportConfig } from '../../integration.constants';import type {IObjectStoreAdapter,IUploadOptions,IUploadResult,} from './types';-// Lazy: constructing a pino logger spins up a worker thread for the-// pino-pretty transport, so a module that is merely imported (every test file-// that reaches the object-store barrel) must not pay for one unused.-let _logger: ILogger | null = null;-function logger(coreConfig: CoreConfig): ILogger {- _logger ??= createLogger({ name: 's3-adapter', config: coreConfig });- return _logger;-}+/** ADR-022 R19: every failure that leaves this adapter is classified as this. */+const S3_PROVIDER = 's3';++// An endpoint the SSRF guard refuses is refused identically on every retry.+const ENDPOINT_REJECTED_RETRYABLE = false;/*** Transport that dials only `address`, whatever DNS says at connect time.@@ -92,9 +93,25 @@ export class S3Adapter implements IObjectStoreAdapter {// between the check and the connect would reach an internal host.// Self-hosted returns null (guard skipped) — a single tenant already owns// the network, and internal MinIO endpoints are a legitimate use.- const addresses = this.config.endpoint- ? await assertSafeUrl(this.coreConfig.selfHosted, this.config.endpoint)- : null;+ //+ // A refused endpoint is refused on every attempt, so it is classified+ // permanent rather than left as a bare throw the caller would have to+ // treat as retryable (ADR-022 R19).+ let addresses: string[] | null = null;+ if (this.config.endpoint) {+ try {+ addresses = await assertSafeUrl(+ this.coreConfig.selfHosted,+ this.config.endpoint+ );+ } catch (error) {+ throw new ProviderError(+ S3_PROVIDER,+ `Endpoint '${this.config.endpoint}' is not a permitted export destination`,+ { retryable: ENDPOINT_REJECTED_RETRYABLE, cause: error }+ );+ }+ }return this.getClientWithAccessKeys(addresses?.[0]);}@@ -134,14 +151,6 @@ export class S3Adapter implements IObjectStoreAdapter {: {}),});- logger(this.coreConfig).debug(- {- region: this.config.region,- endpoint: this.config.endpoint || 'default',- },- 'S3 client created with access keys'- );-// Mark as non-expiringthis.clientExpiresAt = 0;this.clientPromise = Promise.resolve(client);@@ -213,24 +222,13 @@ export class S3Adapter implements IObjectStoreAdapter {},});- logger(this.coreConfig).debug(- {- roleArn: this.config.roleArn,- expiresAt: new Date(this.clientExpiresAt).toISOString(),- },- 'S3 client created with assumed role'- );-return s3Client;} catch (error) {- logger(this.coreConfig).error(- {- error,- roleArn: this.config.roleArn,- },- 'Failed to assume role for S3 access'+ throw providerErrorFrom(+ S3_PROVIDER,+ error,+ `Failed to assume role ${this.config.roleArn} for S3 access`);- throw error;}}@@ -273,36 +271,16 @@ export class S3Adapter implements IObjectStoreAdapter {...this.getEncryptionParams(),};- try {- const command = new PutObjectCommand(putParams);- const response = await client.send(command);-- logger(this.coreConfig).debug(- {- bucket: options.bucket,- key: options.key,- etag: response.ETag,- },- 'File uploaded to S3'- );+ const response = await callProvider(S3_PROVIDER, () =>+ client.send(new PutObjectCommand(putParams))+ );- return {- bucket: options.bucket,- key: options.key,- etag: response.ETag,- location: `s3://${options.bucket}/${options.key}`,- };- } catch (error) {- logger(this.coreConfig).error(- {- error,- bucket: options.bucket,- key: options.key,- },- 'Failed to upload file to S3'- );- throw error;- }+ return {+ bucket: options.bucket,+ key: options.key,+ etag: response.ETag,+ location: `s3://${options.bucket}/${options.key}`,+ };}/**@@ -349,18 +327,12 @@ export class S3Adapter implements IObjectStoreAdapter {* transport detail back to them. The endpoint is caller-supplied, so a* verbatim message ("ECONNREFUSED 10.0.0.5:22", a TLS handshake failure)* would make this procedure a probe for whatever the worker can reach.- * Errors are logged in full for operators.*/private describeError(error: unknown): string {const name = (error as { name?: string } | null)?.name;const status = (error as { $metadata?: { httpStatusCode?: number } } | null)?.$metadata?.httpStatusCode;- logger(this.coreConfig).warn(- { err: error, bucket: this.config.bucket },- 'S3 test failed'- );-if (status === 404 || name === 'NotFound' || name === 'NoSuchBucket') {return `Bucket '${this.config.bucket}' does not exist or is not accessible`;}diff --git a/packages/core/src/clients/integrations/object-store/types.ts b/packages/core/src/modules/integration/src/object-store/types.tssimilarity index 100%rename from packages/core/src/clients/integrations/object-store/types.tsrename to packages/core/src/modules/integration/src/object-store/types.tsdiff --git a/packages/core/src/clients/integrations/registry.test.ts b/packages/core/src/modules/integration/src/registry.test.tssimilarity index 100%rename from packages/core/src/clients/integrations/registry.test.tsrename to packages/core/src/modules/integration/src/registry.test.tsdiff --git a/packages/core/src/clients/integrations/registry.ts b/packages/core/src/modules/integration/src/registry.tssimilarity index 88%rename from packages/core/src/clients/integrations/registry.tsrename to packages/core/src/modules/integration/src/registry.tsindex fdaed2042..9730a4cb9 100644--- a/packages/core/src/clients/integrations/registry.ts+++ b/packages/core/src/modules/integration/src/registry.ts@@ -1,20 +1,30 @@-// Ported from @openpanel/integrations (dissolved into core — M4-005).+// Ported from @openpanel/integrations (dissolved into core — M4-005). Moved+// out of `clients/integrations/` by M15-008: it dispatches to this module's+// own transports, so leaving it below them would have made every one of those+// edges point upward (ADR-022 R22/A2).-import type { CoreConfig } from '../../config';import {- type IIntegrationConfig,- looksEncrypted,-} from '../../modules/integration/integration.constants';-import { type EncryptionKey, encryptCredential } from '../../shared/encryption';+ sendDiscordNotification,+ sendTestDiscordNotification,+} from '../../../clients/integrations/discord';+import {+ postWebhook,+ type WebhookResult,+} from '../../../clients/integrations/fetcher';+import { ProviderError } from '../../../clients/provider-error';+import type { CoreConfig } from '../../../config';+import {+ type EncryptionKey,+ encryptCredential,+} from '../../../shared/encryption';import {execute as executeJavaScriptTemplate,validate as validateJavaScriptTemplate,-} from '../../shared/js-runtime';+} from '../../../shared/js-runtime';import {- sendDiscordNotification,- sendTestDiscordNotification,-} from './discord';-import { postWebhook } from './fetcher';+ type IIntegrationConfig,+ looksEncrypted,+} from '../integration.constants';import {createGCSAdapter,createS3Adapter,@@ -120,6 +130,26 @@ export interface IConfigSecret<C> {record?: boolean;}+/**+ * ADR-022 R19: a delivery that the destination did not accept is a+ * `ProviderError`, carrying the `retryable` the transport already classified.+ * Returning the failed result instead is what let a 500 from a customer's+ * webhook report as a delivered notification.+ */+async function deliverWebhook(+ provider: string,+ send: Promise<WebhookResult>+): Promise<WebhookResult> {+ const result = await send;+ if (!result.ok) {+ throw new ProviderError(provider, `${provider} webhook delivery failed`, {+ status: result.status,+ retryable: result.retryable,+ });+ }+ return result;+}+const slackServer: IServerIntegration<'slack'> = {type: 'slack',// The bot token and the incoming-webhook URL are both bearer credentials for@@ -129,13 +159,16 @@ const slackServer: IServerIntegration<'slack'> = {secretFields: [{ path: 'access_token' }, { path: 'incoming_webhook.url' }],notification: {deliver: ({ config, notification }) =>- sendSlackNotification({- fetcher: safeWebhookFetcher,- webhookUrl: config.incoming_webhook.url,- message: [`🔔 *${notification.title}*`, notification.message].join(- '\n'- ),- }),+ deliverWebhook(+ 'slack',+ sendSlackNotification({+ fetcher: safeWebhookFetcher,+ webhookUrl: config.incoming_webhook.url,+ message: [`🔔 *${notification.title}*`, notification.message].join(+ '\n'+ ),+ })+ ),},};@@ -152,13 +185,16 @@ const discordServer: IServerIntegration<'discord'> = {},notification: {deliver: ({ config, notification }) =>- sendDiscordNotification({- fetcher: safeWebhookFetcher,- webhookUrl: config.url,- message: [`🔔 **${notification.title}**`, notification.message].join(- '\n'- ),- }),+ deliverWebhook(+ 'discord',+ sendDiscordNotification({+ fetcher: safeWebhookFetcher,+ webhookUrl: config.url,+ message: [`🔔 **${notification.title}**`, notification.message].join(+ '\n'+ ),+ })+ ),},};@@ -201,11 +237,9 @@ const webhookServer: IServerIntegration<'webhook'> = {// user-controlled, and this runs inside our network. Re-validate the// destination on every send rather than trusting it from when it was// saved.- return postWebhook(- safeWebhookFetcher,- config.url,- body,- config.headers ?? {}+ return deliverWebhook(+ 'webhook',+ postWebhook(safeWebhookFetcher, config.url, body, config.headers ?? {}));},},diff --git a/packages/core/src/clients/integrations/safe-fetcher.ts b/packages/core/src/modules/integration/src/safe-fetcher.tssimilarity index 83%rename from packages/core/src/clients/integrations/safe-fetcher.tsrename to packages/core/src/modules/integration/src/safe-fetcher.tsindex 325aba14b..70a6c7f85 100644--- a/packages/core/src/clients/integrations/safe-fetcher.ts+++ b/packages/core/src/modules/integration/src/safe-fetcher.ts@@ -1,6 +1,7 @@// Ported from @openpanel/integrations (dissolved into core — M4-005).-import { safeFetch } from '../../shared/safe-fetch';-import type { WebhookFetcher } from './fetcher';++import type { WebhookFetcher } from '../../../clients/integrations/fetcher';+import { safeFetch } from '../../../shared/safe-fetch';/*** Server-side webhook transport. Resolves the host, refuses non-publiclydiff --git a/packages/core/src/clients/integrations/slack.ts b/packages/core/src/modules/integration/src/slack.tssimilarity index 82%rename from packages/core/src/clients/integrations/slack.tsrename to packages/core/src/modules/integration/src/slack.tsindex 5ff35a482..daf3a36d2 100644--- a/packages/core/src/clients/integrations/slack.ts+++ b/packages/core/src/modules/integration/src/slack.ts@@ -1,14 +1,16 @@-// Ported from @openpanel/integrations (dissolved into core — M4-005).+// Ported from @openpanel/integrations (dissolved into core — M4-005). Moved+// out of `clients/integrations/` by M15-008: this module is its only consumer+// (ADR-022 A2).// Cred to (@c_alares) https://github.com/christianalares/seventy-seven/blob/main/packages/integrations/src/slack/index.tsimport * as Slack from '@slack/bolt';-import type { CoreConfig } from '../../config';import {browserFetcher,postWebhook,type WebhookFetcher,type WebhookResult,-} from './fetcher';+} from '../../../clients/integrations/fetcher';+import type { CoreConfig } from '../../../config';const { LogLevel, App: SlackApp } = Slack;@@ -43,6 +45,11 @@ export function slackInstaller(config: CoreConfig): InstallProvider {});}+/**+ * `null` when this deployment has no Slack app configured — ADR-022 R9: a+ * missing thing is null, not an error. The caller decides what an absent+ * install flow means for its own surface.+ */export const getSlackInstallUrl = ({config,integrationId,@@ -53,9 +60,9 @@ export const getSlackInstallUrl = ({integrationId: string;organizationId: string;projectId: string;-}) => {+}): Promise<string> | null => {if (!config.slack.clientId) {- throw new Error('SLACK_CLIENT_ID is not set (slack.ts)');+ return null;}return slackInstaller(config).generateInstallUrl({scopes: INSTALL_SCOPES,diff --git a/packages/core/src/modules/mcp/mcp.service.test.ts b/packages/core/src/modules/mcp/mcp.service.test.tsindex 47f051366..739444e71 100644--- a/packages/core/src/modules/mcp/mcp.service.test.ts+++ b/packages/core/src/modules/mcp/mcp.service.test.ts@@ -63,7 +63,7 @@ const mockFindUnique = mock();const mockGetClientByIdCached = mock();// Real pino would instantiate a pino-pretty transport worker thread whenever-// NODE_ENV isn't 'production' (clients/logger.ts), which intermittently fails+// NODE_ENV isn't 'production' (pino-logger.ts), which intermittently fails// to spawn under Bun. `deps.logger` is an argument now, so the test simply// hands in a noop.const noopLogger = {diff --git a/packages/core/src/modules/notification/notification.jobs.ts b/packages/core/src/modules/notification/notification.jobs.tsindex 154a0657a..35997b473 100644--- a/packages/core/src/modules/notification/notification.jobs.ts+++ b/packages/core/src/modules/notification/notification.jobs.ts@@ -8,6 +8,7 @@import type { Prisma } from '@openpanel/db/src/prisma-client';import { z } from 'zod';+import { isProviderError } from '../../clients/provider-error';import { defineJob } from '../../jobs/define';// A loose mirror of `Prisma.NotificationUncheckedCreateInput` — the payload@@ -32,12 +33,32 @@ export const notificationQueueJobs = {sendNotification: defineJob({payload: z.object({ notification: notificationPayload }),handler: async ({ payload, ctx }) => {- // `payload.notification` round-tripped through BullMQ's JSON storage- // and the loose wire schema above — the real shape is Prisma's create- // input, exactly what a V1 producer put on the queue.- await ctx.services.notification.dispatch(- payload.notification as Prisma.NotificationUncheckedCreateInput- );+ try {+ // `payload.notification` round-tripped through BullMQ's JSON storage+ // and the loose wire schema above — the real shape is Prisma's create+ // input, exactly what a V1 producer put on the queue.+ await ctx.services.notification.dispatch(+ payload.notification as Prisma.NotificationUncheckedCreateInput+ );+ } catch (error) {+ // ADR-022 R19: the transport classified this once. A destination that+ // refused the request (4xx) will refuse the identical retry, so it is+ // logged and the job completes; anything retryable is rethrown so the+ // failure is recorded against the job.+ if (isProviderError(error) && !error.retryable) {+ ctx.logger.error(+ {+ err: error,+ provider: error.provider,+ status: error.status,+ integrationId: payload.notification.integrationId,+ },+ 'Notification permanently refused by the destination'+ );+ return;+ }+ throw error;+ }},}),};diff --git a/packages/core/src/modules/notification/notification.service.ts b/packages/core/src/modules/notification/notification.service.tsindex d3f35dd29..98f4bb154 100644--- a/packages/core/src/modules/notification/notification.service.ts+++ b/packages/core/src/modules/notification/notification.service.ts@@ -19,7 +19,6 @@import type { Integration, Prisma } from '@openpanel/db/src/prisma-client';import { pathOr } from 'ramda';import { sendEmail } from '../../clients/email';-import { getServerIntegration } from '../../clients/integrations/registry';import { TRPCBadRequestError, TRPCForbiddenError } from '../../rpc/errors';import type { ServiceDeps, Services } from '../../services';import { cacheablePerDeps } from '../../shared/cacheable-per-deps';@@ -32,6 +31,7 @@ import {type IIntegrationConfig,isKind,} from '../integration/integration.constants';+import { getServerIntegration } from '../integration/src/registry';import type {IChartEvent,IChartEventFilter,diff --git a/packages/core/src/modules/organization/organization.jobs.ts b/packages/core/src/modules/organization/organization.jobs.tsindex 1cb813e0e..1e3aee59b 100644--- a/packages/core/src/modules/organization/organization.jobs.ts+++ b/packages/core/src/modules/organization/organization.jobs.ts@@ -49,7 +49,7 @@ export const organizationCronJobs = {* The wind-down cron's dependencies, bound to the job's own ctx.** Two reaches stay dynamic. The sibling service's two ClickHouse counts are- * not on `OrganizationService`, and `clients/ai/win-back.ts` pulls the agent+ * not on `OrganizationService`, and `src/win-back-pitch.ts` pulls the agent* runtime — a static edge from here would drag either into jobs.registry.ts's* eager import graph, which every core test file walks.*/@@ -59,7 +59,7 @@ async function windDownDeps(ctx: Ctx, logger: Logger): Promise<WindDownDeps> {{ generateWinBackPitch },] = await Promise.all([import('./organization.service'),- import('../../clients/ai/win-back'),+ import('./src/win-back-pitch'),]);const highlight: WinBackHighlightDeps = {diff --git a/packages/core/src/clients/ai/win-back.ts b/packages/core/src/modules/organization/src/win-back-pitch.tssimilarity index 86%rename from packages/core/src/clients/ai/win-back.tsrename to packages/core/src/modules/organization/src/win-back-pitch.tsindex 1c0cb8621..6807b9e74 100644--- a/packages/core/src/clients/ai/win-back.ts+++ b/packages/core/src/modules/organization/src/win-back-pitch.ts@@ -8,11 +8,15 @@// the same facts.import { betterAgent, defineAgent } from '@better-agent/core';import { z } from 'zod';-import type { CoreConfig } from '../../config';-import { ALLOWED_MODELS, resolveModel } from './providers';+import { callProvider } from '../../../clients/provider-error';+import type { CoreConfig } from '../../../config';+import { ALLOWED_MODELS, resolveModel } from '../../assistant/src/providers';const WIN_BACK_MODEL_ID = 'gpt-4-1-mini';+// Preferred model and fallback are both OpenAI — see insight/src/enrich.ts.+const WIN_BACK_PROVIDER = 'openai';+function winBackModel(config: CoreConfig) {const entry =ALLOWED_MODELS.find((m) => m.id === WIN_BACK_MODEL_ID) ??@@ -83,11 +87,13 @@ export async function generateWinBackPitch(config: CoreConfig,input: WinBackPitchInput): Promise<string> {- const result = (await getApp(config).run('win-back-pitch', {- input: JSON.stringify(input),- context: {},- // biome-ignore lint/suspicious/noExplicitAny: same dodge as enrich.ts- } as any)) as { structured?: { pitch: string } };+ const result = (await callProvider(WIN_BACK_PROVIDER, () =>+ getApp(config).run('win-back-pitch', {+ input: JSON.stringify(input),+ context: {},+ // biome-ignore lint/suspicious/noExplicitAny: same dodge as enrich.ts+ } as any)+ )) as { structured?: { pitch: string } };// The instruction bans em dashes, but the model slips one in often enough// that a prompt rule alone won't hold across hundreds of sends. Commas readdiff --git a/packages/core/src/clients/logger.ts b/packages/core/src/pino-logger.tssimilarity index 99%rename from packages/core/src/clients/logger.tsrename to packages/core/src/pino-logger.tsindex cc28030b1..665938019 100644--- a/packages/core/src/clients/logger.ts+++ b/packages/core/src/pino-logger.ts@@ -9,7 +9,7 @@import * as HyperDX from '@hyperdx/node-opentelemetry';import pino, { type Logger as PinoLogger } from 'pino';-import type { CoreConfig } from '../config';+import type { CoreConfig } from './config';export type ILogger = PinoLogger;