@undefineds.co/xpod 0.4.20 → 0.4.25

package/dist/api/ai-gateway/providers/ProviderRegistry.js

@@ -6,11 +6,12 @@ exports.createDefaultProviderRegistry = createDefaultProviderRegistry;
 exports.providerProductsForDeployment = providerProductsForDeployment;
 exports.offeringDeclaresUpstreamCapability = offeringDeclaresUpstreamCapability;
 exports.normalizeProviderId = normalizeProviderId;
-const models_1 = require("@undefineds.co/models");
 const defaultEmbeddingProfile_1 = require("../../../ai/service/defaultEmbeddingProfile");
 const provider_catalog_1 = require("@undefineds.co/ai-connections/provider-catalog");
 const OfferingAuthorization_1 = require("./OfferingAuthorization");
-exports.OPENAI_SUBSCRIPTION_BASE_URL = 'https://chatgpt.com/backend-api/codex';
+exports.OPENAI_SUBSCRIPTION_BASE_URL = provider_catalog_1.PROVIDER_OFFERINGS.openai
+    .find((offering) => offering.id === 'official-subscription').endpoints
+    .find((endpoint) => endpoint.protocol === 'responses').baseUrl;
 exports.MANAGED_PROVIDER_VOCABULARY = [
     { id: 'openai', runtimeIds: ['codex'], modelsDevId: 'openai' },
     { id: 'anthropic', runtimeIds: ['claude'], modelsDevId: 'anthropic' },
@@ -319,7 +320,7 @@ function providerProductsForDeployment(deployment) {
         }),
     }));
 }
-function catalogOffering(productId, productLabel, input) {
+function catalogOffering(input) {
     const consoleUrl = input.consoleUrl ?? input.subscriptionUrl;
     if (!consoleUrl)
         throw new Error(`Provider offering "${input.id}" requires a console URL`);
@@ -331,7 +332,6 @@ function catalogOffering(productId, productLabel, input) {
     const quota = input.quota ?? { strategy: 'console', url: consoleUrl };
     return {
         ...input,
-        productLabel,
         credentialPrefixHints: input.credentialPrefixHints ?? [],
         consoleUrl,
         subscriptionUrl: input.subscriptionUrl ?? consoleUrl,
@@ -384,16 +384,6 @@ function defaultUpstreamCapabilities(endpoints, modelDiscovery, quota) {
 // authorization actions that a property-definition package must not own. Only
 // the runtime capability descriptors below stay server-side - they describe how
 // Xpod talks to an upstream, which is behaviour rather than shared content.
-const PROVIDER_PRODUCT_LABELS = {
-    openai: 'OpenAI',
-    anthropic: 'Anthropic',
-    kimi: 'Moonshot (Kimi)',
-    bailian: 'Alibaba Bailian',
-    deepseek: 'DeepSeek',
-    ollama: 'Ollama',
-    zhipu: '智谱 AI',
-    custom: 'Custom Provider',
-};
 const PROVIDER_UPSTREAM_OVERRIDES = {
     openai: {
         'official-subscription': [
@@ -490,123 +480,22 @@ function offeringsForProduct(provider) {
         return provider_catalog_1.CUSTOM_DEFAULT_OFFERINGS;
     return provider_catalog_1.PROVIDER_OFFERINGS[provider] ?? provider_catalog_1.DEFAULT_PROVIDER_OFFERINGS;
 }
-const LEGACY_PROVIDER_PRODUCT_DESCRIPTORS = Object.keys(PROVIDER_PRODUCT_LABELS).map((provider) => ({
+/** Project capability-owned product content; only upstream implementation choices stay here. */
+exports.DEFAULT_PROVIDER_PRODUCT_DESCRIPTORS = Object.entries(provider_catalog_1.PROVIDER_LABELS).map(([provider, label]) => ({
     id: provider,
-    label: PROVIDER_PRODUCT_LABELS[provider],
-    offerings: offeringsForProduct(provider).map((offering) => 
-    // The shared catalog is the source of the offering content; the server's
-    // descriptor type narrows the same fields, so the projection converts at
-    // this boundary rather than duplicating the values.
-    catalogOffering(provider, PROVIDER_PRODUCT_LABELS[provider], {
+    label,
+    offerings: offeringsForProduct(provider).map((offering) => catalogOffering({
         ...offering,
-        endpoints: offering.endpoints ?? [],
+        productLabel: offering.productLabel ?? label,
+        runtimeProviderIds: offering.runtimeProviderIds ?? [provider],
+        endpoints: (offering.endpoints ?? [])
+            .map((endpoint) => ({ ...endpoint, protocol: toGatewayProtocol(endpoint.protocol) }))
+            .filter((endpoint) => endpoint.protocol !== undefined),
         ...(PROVIDER_UPSTREAM_OVERRIDES[provider]?.[offering.id]
             ? { upstream: PROVIDER_UPSTREAM_OVERRIDES[provider][offering.id] }
             : {}),
     })),
 }));
-/**
- * The provider/offering catalog belongs to `@undefineds.co/ai-connections`: it
- * is content rather than schema, and it carries endpoints, console links and
- * authorization actions that a property-definition package must not own. The
- * descriptors above are the pre-existing copy that is being replaced by that
- * shared catalog; only runtime capability descriptors stay server-side.
- */
-exports.DEFAULT_PROVIDER_PRODUCT_DESCRIPTORS = canonicalProviderProducts(LEGACY_PROVIDER_PRODUCT_DESCRIPTORS)
-    .map(normalizeOpenAiSubscriptionProduct);
-function canonicalProviderProducts(legacy) {
-    return legacy.map((fallback) => {
-        const canonicalSlug = discoveryProviderSlug(fallback.id);
-        const provider = (0, models_1.getBuiltinProvider)(canonicalSlug);
-        if (!provider?.offerings?.length)
-            return fallback;
-        return {
-            id: fallback.id,
-            label: provider.displayName || fallback.label,
-            offerings: provider.offerings.map((offering) => canonicalOfferingDescriptor(provider, offering, fallback.offerings.find((candidate) => candidate.id === offering.id))),
-        };
-    }).concat(canonicalStandaloneProducts());
-}
-function normalizeOpenAiSubscriptionProduct(product) {
-    if (product.id !== 'openai') {
-        return product;
-    }
-    return {
-        ...product,
-        offerings: product.offerings.map((offering) => offering.id === 'official-subscription'
-            ? {
-                ...offering,
-                label: 'OpenAI Subscription',
-                authModes: ['local'],
-                auth: [{ protocol: 'local-none' }],
-                consoleUrl: 'https://chatgpt.com/',
-                subscriptionUrl: 'https://chatgpt.com/#pricing',
-                quota: { strategy: 'subscription', url: 'https://chatgpt.com/' },
-                endpoints: [{ protocol: 'responses', baseUrl: exports.OPENAI_SUBSCRIPTION_BASE_URL }],
-                lifecycle: 'unavailable',
-            }
-            : offering),
-    };
-}
-function canonicalStandaloneProducts() {
-    const fallback = new Map(LEGACY_PROVIDER_PRODUCT_DESCRIPTORS.map((product) => [product.id, product]));
-    const ollama = (0, models_1.getBuiltinProvider)('ollama');
-    if (!ollama?.offerings?.length || fallback.has('ollama'))
-        return [];
-    return [{
-            id: 'ollama',
-            label: ollama.displayName,
-            offerings: ollama.offerings.map((offering) => canonicalOfferingDescriptor(ollama, offering)),
-        }];
-}
-function canonicalOfferingDescriptor(provider, offering, fallback) {
-    const endpoints = offering.endpoints
-        .map((endpoint) => ({
-        ...endpoint,
-        protocol: toGatewayProtocol(endpoint.protocol),
-    }))
-        .filter((endpoint) => endpoint.protocol !== undefined);
-    const modelDiscovery = offering.modelDiscovery
-        ? {
-            strategy: offering.modelDiscovery.strategy,
-            path: offering.modelDiscovery.path,
-            endpointProtocol: toGatewayProtocol(offering.modelDiscovery.endpointProtocol)
-                ?? endpoints[0]?.protocol
-                ?? 'chatCompletions',
-        }
-        : fallback?.modelDiscovery ?? {
-            strategy: endpoints[0]?.protocol === 'anthropic' ? 'anthropic' : 'openaiCompatible',
-            path: '/models',
-            endpointProtocol: endpoints[0]?.protocol ?? 'chatCompletions',
-        };
-    const quota = offering.quota ?? fallback?.quota ?? {
-        strategy: 'unsupported',
-        url: offering.consoleUrl ?? provider.homepage,
-    };
-    return {
-        id: offering.id,
-        runtimeProviderIds: offering.runtimeProviderIds ?? [provider.slug],
-        label: offering.label,
-        productLabel: offering.productLabel ?? provider.displayName,
-        kind: offering.kind,
-        authModes: offering.authModes,
-        // The canonical source carries schema, not actions: which connect entries an
-        // offering declares stays with the catalog that declared them.
-        ...(fallback?.authorizationMethods ? { authorizationMethods: fallback.authorizationMethods } : {}),
-        auth: fallback?.auth ?? defaultAuthCapabilities(offering.kind, offering.authModes),
-        upstream: fallback?.upstream ?? defaultUpstreamCapabilities(endpoints, modelDiscovery, quota),
-        endpoints,
-        credentialPrefixHints: offering.credentialPrefixHints ?? fallback?.credentialPrefixHints ?? [],
-        consoleUrl: offering.consoleUrl ?? fallback?.consoleUrl ?? provider.homepage,
-        subscriptionUrl: offering.subscriptionUrl ?? fallback?.subscriptionUrl ?? offering.consoleUrl ?? provider.homepage,
-        modelDiscovery,
-        quota,
-        usagePolicyUrl: offering.usagePolicyUrl ?? fallback?.usagePolicyUrl ?? provider.homepage,
-        region: offering.region ?? fallback?.region ?? 'global',
-        lifecycle: offering.lifecycle ?? fallback?.lifecycle ?? 'active',
-        ...(fallback?.oauthIntegrationId ? { oauthIntegrationId: fallback.oauthIntegrationId } : {}),
-    };
-}
 function toGatewayProtocol(value) {
     return value === 'responses' || value === 'anthropic' || value === 'chatCompletions'
         ? value
@@ -615,7 +504,7 @@ function toGatewayProtocol(value) {
 exports.DEFAULT_PROVIDER_DESCRIPTORS = [
     {
         id: 'openai',
-        label: 'OpenAI',
+        label: provider_catalog_1.PROVIDER_LABELS.openai,
         authModes: ['browserAssistedApiKey', 'apiKey'],
         connect: {
             mode: 'browserAssistedApiKey',
@@ -645,7 +534,7 @@ exports.DEFAULT_PROVIDER_DESCRIPTORS = [
     },
     {
         id: 'anthropic',
-        label: 'Anthropic',
+        label: provider_catalog_1.PROVIDER_LABELS.anthropic,
         authModes: ['browserAssistedApiKey', 'apiKey'],
         connect: {
             mode: 'browserAssistedApiKey',
@@ -671,7 +560,7 @@ exports.DEFAULT_PROVIDER_DESCRIPTORS = [
     },
     {
         id: 'kimi',
-        label: 'Kimi',
+        label: provider_catalog_1.PROVIDER_LABELS.kimi,
         authModes: ['browserAssistedApiKey', 'apiKey'],
         connect: {
             mode: 'browserAssistedApiKey',
@@ -696,7 +585,7 @@ exports.DEFAULT_PROVIDER_DESCRIPTORS = [
     },
     {
         id: 'bailian',
-        label: 'Alibaba Bailian',
+        label: provider_catalog_1.PROVIDER_LABELS.bailian,
         authModes: ['browserAssistedApiKey', 'apiKey'],
         connect: {
             mode: 'browserAssistedApiKey',
@@ -728,7 +617,7 @@ exports.DEFAULT_PROVIDER_DESCRIPTORS = [
     },
     {
         id: 'deepseek',
-        label: 'DeepSeek',
+        label: provider_catalog_1.PROVIDER_LABELS.deepseek,
         authModes: ['browserAssistedApiKey', 'apiKey'],
         connect: {
             mode: 'browserAssistedApiKey',
@@ -764,7 +653,7 @@ exports.DEFAULT_PROVIDER_DESCRIPTORS = [
     },
     {
         id: 'zhipu',
-        label: '智谱 AI',
+        label: provider_catalog_1.PROVIDER_LABELS.zhipu,
         authModes: ['browserAssistedApiKey', 'apiKey'],
         connect: {
             mode: 'browserAssistedApiKey',
@@ -793,7 +682,7 @@ exports.DEFAULT_PROVIDER_DESCRIPTORS = [
     },
     {
         id: 'ollama',
-        label: 'Ollama',
+        label: provider_catalog_1.PROVIDER_LABELS.ollama,
         authModes: ['connectUnsupported'],
         connect: {
             mode: 'connectUnsupported',
@@ -814,7 +703,7 @@ exports.DEFAULT_PROVIDER_DESCRIPTORS = [
     },
     {
         id: 'custom',
-        label: 'Custom Provider',
+        label: provider_catalog_1.PROVIDER_LABELS.custom,
         authModes: ['apiKey'],
         connect: {
             mode: 'browserAssistedApiKey',

package/dist/api/ai-gateway/providers/ProviderRuntimeAdapter.d.ts

@@ -1,3 +1,4 @@
+import { type GatewayInvocationMetadata } from '../InvocationMetadata';
 import { type GatewayEvent, type GatewayRequest, type GatewayUsage } from '../types';
 import { type ProviderSseEvent, ProviderHttpTransport } from '../../service/provider-http-transport';
 import type { ProviderDescriptor, ProviderModelDescriptor } from './ProviderRegistry';
@@ -18,6 +19,7 @@ export interface ProviderRuntimeExecuteInput {
     apiKey: string;
     credential?: ProviderRuntimeCredential;
     signal?: AbortSignal;
+    invocationMetadata?: GatewayInvocationMetadata;
 }
 export interface ProviderRuntimeAdapter {
     readonly provider: string;
@@ -99,4 +101,4 @@ export declare function parseChatUsage(usage: Record<string, unknown>): GatewayU
 export declare function objectField(record: Record<string, unknown>, key: string): Record<string, unknown>;
 export declare function stringField(record: Record<string, unknown>, key: string): string | undefined;
 export declare function numberField(record: Record<string, unknown>, key: string): number | undefined;
-export declare function classifyProviderStatus(status: number): string;
+export declare function classifyProviderStatus(status: number, code?: string): string;

package/dist/api/ai-gateway/providers/ProviderRuntimeAdapter.js

@@ -15,6 +15,7 @@ exports.objectField = objectField;
 exports.stringField = stringField;
 exports.numberField = numberField;
 exports.classifyProviderStatus = classifyProviderStatus;
+const InvocationMetadata_1 = require("../InvocationMetadata");
 const errors_1 = require("../errors");
 const types_1 = require("../types");
 const provider_http_transport_1 = require("../../service/provider-http-transport");
@@ -57,7 +58,7 @@ class BaseProviderRuntimeAdapter {
             details: {
                 provider: this.provider,
                 providerStatusCode: status,
-                classification: classifyProviderStatus(status),
+                classification: classifyProviderStatus(status, providerErrorCode(body)),
                 ...(retryAfter ? { retryAfter } : {}),
                 ...(body ? { body } : {}),
             },
@@ -104,6 +105,7 @@ class OpenAiCompatibleRuntimeAdapter extends BaseProviderRuntimeAdapter {
             yield* parseCompatibleChatSse(this.transport.postSse({
                 url: `${baseUrl}/chat/completions`,
                 apiKey: input.apiKey,
+                headers: (0, InvocationMetadata_1.gatewayInvocationHeaders)(input.invocationMetadata),
                 body,
                 proxy: input.credential?.proxy,
                 signal: input.signal,
@@ -518,6 +520,7 @@ async function* parseCompatibleChatSse(events, secret) {
     const toolArguments = new types_1.ToolArgumentTracker();
     const callIdsByIndex = new Map();
     const openCallIds = new Set();
+    let responseId;
     for await (const event of events) {
         const payload = parseJsonSseData(event.data);
         if (!payload) {
@@ -528,11 +531,14 @@ async function* parseCompatibleChatSse(events, secret) {
         }
         const id = stringField(payload, 'id');
         const choices = Array.isArray(payload.choices) ? payload.choices : [];
-        if (id && choices.some((choice) => {
+        if (id && id !== responseId && choices.some((choice) => {
             const delta = objectField(choice, 'delta');
             const message = objectField(choice, 'message');
             return delta.role === 'assistant' || message.role === 'assistant';
         })) {
+            // Repeated assistant roles belong to the same response. Keep its tool indexes
+            // so subsequent arguments-only chunks can resolve the original call ID.
+            responseId = id;
             toolArguments.reset();
             callIdsByIndex.clear();
             openCallIds.clear();
@@ -641,7 +647,9 @@ function numberField(record, key) {
     const value = record[key];
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
-function classifyProviderStatus(status) {
+function classifyProviderStatus(status, code) {
+    if (code === 'insufficient_quota' || code === 'billing_hard_limit_reached')
+        return 'quota_exhausted';
     if (status === 401) {
         return 'authentication';
     }
@@ -791,7 +799,7 @@ function providerStreamError(payload, status, secret) {
         status,
         details: {
             providerStatusCode: status,
-            classification: classifyProviderStatus(status),
+            classification: classifyProviderStatus(status, stringField(error, 'code') ?? stringField(error, 'type')),
             providerErrorType: stringField(error, 'type') ?? stringField(payload, 'type'),
         },
     });
@@ -845,4 +853,17 @@ function safeNormalizeRuntimeBaseUrl(value) {
 function redactSecret(value, secret) {
     return secret ? value.split(secret).join('[REDACTED]') : value;
 }
+/** Only inspect an upstream error's stable code; never persist its body. */
+function providerErrorCode(body) {
+    if (!body)
+        return undefined;
+    try {
+        const value = JSON.parse(body);
+        return typeof value?.error?.code === 'string' ? value.error.code
+            : typeof value?.error?.type === 'string' ? value.error.type : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=ProviderRuntimeAdapter.js.map

package/dist/api/ai-gateway/routing/ModelRouter.js

@@ -318,6 +318,19 @@ class ModelRouter {
         if (registryMatches.length > 0) {
             const candidateMatch = registryMatches.find((match) => candidates.some((candidate) => this.credentialMatchesProvider(candidate, match.provider.id)
                 && credentialSupportsModel(candidate, match.model.id)));
+            // A compatible endpoint can explicitly offer a catalog model without
+            // belonging to its original provider. Unrestricted credentials alone do
+            // not establish that cross-provider route.
+            if (!candidateMatch) {
+                const declaredCandidate = candidates.find((candidate) => candidate.models !== undefined && credentialSupportsModel(candidate, model));
+                if (declaredCandidate) {
+                    return {
+                        providerId: this.routeProviderIdForCredential(declaredCandidate),
+                        model,
+                        source: 'exact-model',
+                    };
+                }
+            }
             const match = candidateMatch ?? registryMatches[0];
             return {
                 providerId: (0, ProviderRegistry_1.normalizeProviderId)(match.provider.id),

package/dist/api/auth/SolidSessionFactory.d.ts

@@ -49,6 +49,7 @@ export declare class SolidSessionFactory {
     private readonly now;
     private readonly maxEntries;
     private readonly sessions;
+    private readonly pending;
     /** Cache keys per client id, so a revoked credential can be forgotten without its secret. */
     private readonly keysByClientId;
     private readonly clientIdByKey;
@@ -72,7 +73,7 @@ export declare class SolidSessionFactory {
      * The caller retries with a fresh exchange rather than a different identity: a rejected token
      * says nothing about who the caller is.
      */
-    invalidate(credential: SolidClientCredential): void;
+    invalidate(credential: SolidClientCredential, expectedSession?: SolidSession): void;
     private exchange;
 }
 export declare class SolidSessionError extends Error {

package/dist/api/auth/SolidSessionFactory.js

@@ -22,6 +22,7 @@ class SolidSessionFactory {
     constructor(options) {
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
         this.sessions = new Map();
+        this.pending = new Map();
         /** Cache keys per client id, so a revoked credential can be forgotten without its secret. */
         this.keysByClientId = new Map();
         this.clientIdByKey = new Map();
@@ -37,10 +38,25 @@ class SolidSessionFactory {
         if (cached && cached.expiresAt > this.now() + TOKEN_EXPIRY_SKEW_MS) {
             return cached;
         }
+        const existing = this.pending.get(key);
+        if (existing) {
+            return existing.promise;
+        }
         this.forgetKey(key);
-        const session = await this.exchange(credential);
-        this.remember(key, credential.clientId, session);
-        return session;
+        const promise = this.exchange(credential).then((session) => {
+            if (this.pending.get(key) !== pending) {
+                throw new SolidSessionError('token_exchange_invalidated');
+            }
+            this.remember(key, credential.clientId, session);
+            return session;
+        }).finally(() => {
+            if (this.pending.get(key) === pending) {
+                this.pending.delete(key);
+            }
+        });
+        const pending = { clientId: credential.clientId, promise };
+        this.pending.set(key, pending);
+        return promise;
     }
     /**
      * Forget every cached session for one client.
@@ -51,14 +67,14 @@ class SolidSessionFactory {
      */
     invalidateClientCredential(clientId) {
         const keys = this.keysByClientId.get(clientId);
-        if (!keys) {
-            return;
+        for (const key of keys ?? []) {
+            this.forgetKey(key);
         }
-        for (const key of keys) {
-            this.sessions.delete(key);
-            this.clientIdByKey.delete(key);
+        for (const [key, pending] of this.pending) {
+            if (pending.clientId === clientId) {
+                this.pending.delete(key);
+            }
         }
-        this.keysByClientId.delete(clientId);
     }
     remember(key, clientId, session) {
         this.sessions.set(key, session);
@@ -91,8 +107,14 @@ class SolidSessionFactory {
      * The caller retries with a fresh exchange rather than a different identity: a rejected token
      * says nothing about who the caller is.
      */
-    invalidate(credential) {
-        this.forgetKey(cacheKey(this.route, credential));
+    invalidate(credential, expectedSession) {
+        const key = cacheKey(this.route, credential);
+        // A late rejection of an old token cannot evict its replacement or pending renewal.
+        if (expectedSession && this.sessions.get(key) !== expectedSession) {
+            return;
+        }
+        this.pending.delete(key);
+        this.forgetKey(key);
     }
     async exchange(credential) {
         const dpopKey = await (0, solid_client_authn_core_1.generateDpopKeyPair)();

package/dist/api/background-service-supervisor.d.ts

@@ -0,0 +1,63 @@
+import { getLoggerFor } from 'global-logger-factory';
+/**
+ * Keeps a background service alive instead of starting it once (audit N18).
+ *
+ * `startBackgroundServices()` ran each service exactly once and logged whatever failed, so a
+ * tunnel or DDNS client that could not start (offline at boot, provider hiccup) stayed down for
+ * the lifetime of the process, and one that died later was never noticed. This supervisor owns
+ * that loop: bounded exponential backoff while starting, a periodic liveness check once it is
+ * up, and a stop() that really stops (a pending retry must not resurrect it — the same failure
+ * mode the process supervisor had).
+ */
+export interface BackgroundServiceSupervisorOptions {
+    name: string;
+    /** Starts the service; may throw. Must be safe to call again after a failure. */
+    start: () => Promise<void> | void;
+    /** Stops the service (used by stop()). */
+    stop?: () => Promise<void> | void;
+    /**
+     * Reports whether the service is still up. When provided, the supervisor restarts it after a
+     * liveness check fails; without it, supervision covers startup only.
+     */
+    isRunning?: () => boolean | Promise<boolean>;
+    retryBaseDelayMs?: number;
+    retryMaxDelayMs?: number;
+    checkIntervalMs?: number;
+    now?: () => Date;
+    logger?: Pick<ReturnType<typeof getLoggerFor>, 'info' | 'warn' | 'error'>;
+}
+export interface BackgroundServiceSupervisorStatus {
+    name: string;
+    state: 'idle' | 'starting' | 'running' | 'retrying' | 'stopped';
+    attempts: number;
+    restarts: number;
+    lastError?: string;
+    startedAt?: string;
+    nextRetryInMs?: number;
+}
+export declare class BackgroundServiceSupervisor {
+    private readonly options;
+    private readonly logger;
+    private readonly now;
+    private readonly retryBaseDelayMs;
+    private readonly retryMaxDelayMs;
+    private readonly checkIntervalMs;
+    private timer?;
+    private running;
+    private inFlight;
+    private consecutiveFailures;
+    private restarts;
+    private status;
+    constructor(options: BackgroundServiceSupervisorOptions);
+    /** Starts supervising; repeated calls are a no-op so a restart cannot double the timers. */
+    start(): void;
+    stop(): Promise<void>;
+    getStatus(): BackgroundServiceSupervisorStatus;
+    /** One start-or-check cycle, exposed so an operator action or a test can drive it. */
+    runOnce(): Promise<BackgroundServiceSupervisorStatus>;
+    nextDelayMs(): number;
+    private attempt;
+    private checkAlive;
+    /** Schedules the next cycle from the current state; the loop owns its own timer. */
+    scheduleNext(): void;
+}

package/dist/api/background-service-supervisor.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackgroundServiceSupervisor = void 0;
+const global_logger_factory_1 = require("global-logger-factory");
+const DEFAULT_RETRY_BASE_DELAY_MS = 5_000;
+const DEFAULT_RETRY_MAX_DELAY_MS = 5 * 60_000;
+const DEFAULT_CHECK_INTERVAL_MS = 30_000;
+class BackgroundServiceSupervisor {
+    constructor(options) {
+        this.options = options;
+        this.running = false;
+        this.inFlight = false;
+        this.consecutiveFailures = 0;
+        this.restarts = 0;
+        this.logger = options.logger ?? (0, global_logger_factory_1.getLoggerFor)('BackgroundServiceSupervisor');
+        this.now = options.now ?? (() => new Date());
+        this.retryBaseDelayMs = positive(options.retryBaseDelayMs, DEFAULT_RETRY_BASE_DELAY_MS);
+        this.retryMaxDelayMs = positive(options.retryMaxDelayMs, DEFAULT_RETRY_MAX_DELAY_MS);
+        this.checkIntervalMs = positive(options.checkIntervalMs, DEFAULT_CHECK_INTERVAL_MS);
+        this.status = { name: options.name, state: 'idle', attempts: 0, restarts: 0 };
+    }
+    /** Starts supervising; repeated calls are a no-op so a restart cannot double the timers. */
+    start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.status = { ...this.status, state: 'starting', nextRetryInMs: undefined };
+        // One cycle now, then the loop keeps its own timer.
+        void this.runOnce().then(() => this.scheduleNext());
+    }
+    async stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.status = { ...this.status, state: 'stopped', nextRetryInMs: undefined };
+        try {
+            await this.options.stop?.();
+        }
+        catch (error) {
+            this.logger.warn(`${this.options.name}: stop failed: ${message(error)}`);
+        }
+    }
+    getStatus() {
+        return { ...this.status };
+    }
+    /** One start-or-check cycle, exposed so an operator action or a test can drive it. */
+    async runOnce() {
+        if (this.inFlight) {
+            return this.getStatus();
+        }
+        this.inFlight = true;
+        try {
+            if (this.status.state === 'running') {
+                return await this.checkAlive();
+            }
+            return await this.attempt();
+        }
+        finally {
+            this.inFlight = false;
+        }
+    }
+    nextDelayMs() {
+        if (this.consecutiveFailures === 0) {
+            return this.checkIntervalMs;
+        }
+        const exponent = Math.max(0, this.consecutiveFailures - 1);
+        return Math.min(this.retryBaseDelayMs * 2 ** exponent, this.retryMaxDelayMs);
+    }
+    async attempt() {
+        this.status = { ...this.status, attempts: this.status.attempts + 1 };
+        try {
+            await this.options.start();
+            this.consecutiveFailures = 0;
+            this.status = {
+                ...this.status,
+                state: 'running',
+                lastError: undefined,
+                startedAt: this.now().toISOString(),
+            };
+            this.logger.info(`${this.options.name}: started`);
+            return this.getStatus();
+        }
+        catch (error) {
+            this.consecutiveFailures += 1;
+            const delay = this.nextDelayMs();
+            this.status = {
+                ...this.status,
+                state: 'retrying',
+                lastError: message(error),
+                nextRetryInMs: delay,
+            };
+            this.logger.warn(`${this.options.name}: start failed (attempt ${this.status.attempts}), retrying in ${delay}ms: ${message(error)}`);
+            return this.getStatus();
+        }
+    }
+    async checkAlive() {
+        if (!this.options.isRunning) {
+            return this.getStatus();
+        }
+        let alive;
+        try {
+            alive = await this.options.isRunning();
+        }
+        catch (error) {
+            alive = false;
+            this.logger.warn(`${this.options.name}: liveness check failed: ${message(error)}`);
+        }
+        if (alive) {
+            return this.getStatus();
+        }
+        this.restarts += 1;
+        this.consecutiveFailures = 0;
+        this.status = { ...this.status, restarts: this.restarts };
+        this.logger.warn(`${this.options.name}: not running any more; restarting (restart ${this.restarts})`);
+        // Restart in this cycle rather than waiting for the next check.
+        return await this.attempt();
+    }
+    /** Schedules the next cycle from the current state; the loop owns its own timer. */
+    scheduleNext() {
+        if (!this.running) {
+            return;
+        }
+        const delay = this.status.state === 'running' && this.options.isRunning
+            ? this.checkIntervalMs
+            : this.nextDelayMs();
+        this.status = { ...this.status, nextRetryInMs: delay };
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.runOnce().then(() => this.scheduleNext());
+        }, delay);
+        this.timer.unref?.();
+    }
+}
+exports.BackgroundServiceSupervisor = BackgroundServiceSupervisor;
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function positive(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+//# sourceMappingURL=background-service-supervisor.js.map