@cerebriline/core 4.100.240

package/dist/services/connectors/connector-autostart.d.ts

@@ -0,0 +1,33 @@
+import { type ConnectorConnectionRecord } from "@cerebriline/shared/db";
+/**
+ * Record a successful connector start so the connector can be reconnected
+ * automatically after a hub or host restart.
+ */
+export declare function persistConnectorConnection(channel: string, instanceId: string, rawArgs: string[], cwd?: string): void;
+/** Stop auto-reconnecting one instance, one channel, or every connector. */
+export declare function disableConnectorAutostart(channel?: string, instanceId?: string): void;
+export declare function getPersistedConnectorConnection(channel: string, instanceId: string): ConnectorConnectionRecord | undefined;
+export declare function removePersistedConnectorConnection(channel: string, instanceId: string): void;
+export interface ReconnectTarget {
+    channel: string;
+    instanceId: string;
+    args: string[];
+}
+export interface ReconnectAttempt {
+    channel: string;
+    instanceId: string;
+    ok: boolean;
+    error?: string;
+}
+export interface ReconnectPersistedConnectorsOptions {
+    /** Starts one connector instance with its stored, non-interactive arguments. */
+    start: (target: ReconnectTarget) => Promise<boolean>;
+    /** Reports whether this exact connector instance is healthy in the host. */
+    isHealthy?: (target: ReconnectTarget) => boolean;
+    log?: (message: string) => void;
+}
+/**
+ * Reconnect every connector that has stored connection arguments, is enabled,
+ * and is not already active in the calling host.
+ */
+export declare function reconnectPersistedConnectors(options: ReconnectPersistedConnectorsOptions): Promise<ReconnectAttempt[]>;

package/dist/services/connectors/connector-child-env.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Environment for a CLI process the hub daemon launches.
+ *
+ * The daemon inherits the environment of whichever connector spawned it, and
+ * those inherited markers are actively harmful downstream: the daemon sentinel
+ * would make the child try to become a hub, and a child marker tells a connector
+ * "you are already the detached child", which makes it skip its own
+ * already-running check and start alongside a live instance holding the same
+ * credentials.
+ */
+export declare function buildConnectorChildEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare const __test__: {
+    CONNECTOR_CHILD_MARKER_PATTERN: RegExp;
+};

package/dist/services/connectors/connector-cleanup.d.ts

@@ -0,0 +1,20 @@
+import { spawn } from "node:child_process";
+import { type ConnectorCliLaunchSpec } from "@cerebriline/shared";
+export interface CleanupConnectorInstanceOptions {
+    launchSpec?: ConnectorCliLaunchSpec | undefined;
+    spawnProcess?: typeof spawn;
+    timeoutMs?: number;
+}
+/**
+ * Reap one dead connector instance through the CLI.
+ *
+ * What has to be cleaned up — the process state file, thread→session bindings,
+ * and the hub sessions the connector owned — is all connector-specific knowledge
+ * that lives in the CLI's adapters. Rather than duplicate those conventions in
+ * the hub, the supervisor shells back into the CLI's own stop path, which
+ * already does exactly this for a process that is no longer running.
+ *
+ * `--cleanup-instance` deliberately preserves the autostart record: the instance
+ * died, it was not retired, so the supervisor still intends to restart it.
+ */
+export declare function cleanupConnectorInstanceViaCli(channel: string, instanceId: string, options?: CleanupConnectorInstanceOptions): Promise<void>;

package/dist/services/connectors/connector-supervisor.d.ts

@@ -0,0 +1,134 @@
+import { spawn } from "node:child_process";
+import { type ConnectorCliLaunchSpec, type ConnectorStartRequest, type ConnectorStartResult, type SupervisedConnectorRecord } from "@cerebriline/shared";
+import { listActiveConnectors } from "./active-connectors";
+export declare const RESTART_BASE_DELAY_MS = 1000;
+export declare const RESTART_MAX_DELAY_MS = 60000;
+/** Consecutive failed restarts before the hub stops trying. */
+export declare const RESTART_GIVE_UP_AFTER = 5;
+/**
+ * A run that lasts this long is treated as healthy, clearing the restart
+ * counter. Without it a connector that stays up for hours and then dies would
+ * inherit stale failures and be given up on immediately.
+ */
+export declare const RESTART_COUNTER_RESET_MS = 60000;
+/** How often adopted connectors (no child handle) are checked for liveness. */
+export declare const ADOPTED_POLL_INTERVAL_MS = 5000;
+/** How long a stop waits for SIGTERM to land before escalating to SIGKILL. */
+export declare const STOP_SIGTERM_TIMEOUT_MS = 5000;
+/** How long a stop waits for SIGKILL to land before giving up on the wait. */
+export declare const STOP_SIGKILL_TIMEOUT_MS = 2000;
+export interface ConnectorSupervisorDeps {
+    launchSpec?: () => ConnectorCliLaunchSpec | undefined;
+    spawnProcess?: typeof spawn;
+    isProcessRunning?: (pid: number) => boolean;
+    killProcess?: (pid: number, signal: NodeJS.Signals) => void;
+    listActive?: typeof listActiveConnectors;
+    /**
+     * Reap a dead instance's leftovers: state file, thread bindings and hub
+     * sessions. Delegated because all of that is connector-specific and owned by
+     * the CLI; the supervisor only knows a process died.
+     */
+    cleanupInstance?: (channel: string, instanceId: string) => Promise<void>;
+    isAutostartEnabled?: (channel: string, instanceId: string) => boolean;
+    log?: (message: string) => void;
+    now?: () => number;
+    setTimer?: (callback: () => void, delayMs: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/**
+ * Owns the lifecycle of connector processes on behalf of the hub.
+ *
+ * Three responsibilities, in order of why this exists:
+ *
+ * 1. **Single instance per (channel, instanceId).** The in-memory map is the
+ *    authority, so two connectors can never hold the same bot token because two
+ *    processes raced on a state file.
+ * 2. **Reaping.** When a connector dies its state file, thread bindings and hub
+ *    sessions would otherwise linger until the next manual start, leaving
+ *    Slack threads bound to sessions that no longer exist.
+ * 3. **Restart with backoff.** Replaces external watchdogs, and refuses to
+ *    spin forever on a connector that cannot start (a revoked token).
+ *
+ * Connectors are spawned detached so a hub restart does not take them down; a
+ * later hub adopts the survivors by pid from their state files. That is why exit
+ * detection has two paths: child events for processes this hub spawned, pid
+ * polling for adopted ones.
+ */
+export declare class ConnectorSupervisor {
+    private readonly entries;
+    /**
+     * Tail of the in-flight start/stop chain per instance key. `start` suspends
+     * on `stop` (which shells into the CLI for cleanup, taking seconds), and two
+     * unserialised starts interleaving across that suspension each spawn their
+     * own process — the map ends up tracking one while the other survives as an
+     * untracked ghost holding the connector's credentials and ports.
+     */
+    private readonly instanceLocks;
+    private pollTimer;
+    private disposed;
+    private readonly launchSpec;
+    private readonly spawnProcess;
+    private readonly isProcessRunning;
+    private readonly killProcess;
+    private readonly listActive;
+    private readonly cleanupInstance?;
+    private readonly isAutostartEnabled;
+    private readonly log;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    constructor(deps?: ConnectorSupervisorDeps);
+    /**
+     * Take over connectors that are already running, so a replacement hub reaps
+     * and restarts the processes it inherited instead of ignoring them.
+     */
+    adoptRunningConnectors(): SupervisedConnectorRecord[];
+    /**
+     * Serialise start/stop work per instance key. Both operations suspend
+     * mid-flight — a stop waits for the process to die and for the CLI cleanup,
+     * a start may embed a stop — and interleaving two of them across those
+     * suspensions is how the map ends up tracking one process while another
+     * lives on untracked. One instance, one queue.
+     */
+    private withInstanceLock;
+    start(request: ConnectorStartRequest): Promise<ConnectorStartResult>;
+    private startLocked;
+    stop(request: {
+        channel: string;
+        instanceId: string;
+        disableAutostart?: boolean;
+    }): Promise<boolean>;
+    private stopLocked;
+    private signal;
+    private waitForProcessExit;
+    list(): SupervisedConnectorRecord[];
+    /**
+     * Stop supervising without touching the processes: they are detached and
+     * outlive this hub on purpose, and the next hub adopts them.
+     */
+    dispose(): void;
+    private spawnEntry;
+    private handleExit;
+    private scheduleRestart;
+    /**
+     * An adopted connector has no argv of its own here, so its restart arguments
+     * come from the persisted autostart record.
+     */
+    private resolveRestartArgs;
+    private cancelRestart;
+    private runCleanup;
+    private isEntryAlive;
+    /**
+     * Adopted connectors have no child handle, so their death is only visible by
+     * polling. Processes this hub spawned report their own exit and are skipped.
+     */
+    private ensurePolling;
+    private hasAdoptedRunning;
+    private toRecord;
+}
+/**
+ * The hub daemon's supervisor. Hub command handlers reach it through here
+ * because they are invoked per-request and have no other shared state.
+ */
+export declare function setActiveConnectorSupervisor(supervisor: ConnectorSupervisor | undefined): void;
+export declare function getActiveConnectorSupervisor(): ConnectorSupervisor | undefined;

package/dist/services/connectors/daemon-connector-reconnect.d.ts

@@ -0,0 +1,15 @@
+import { type ReconnectAttempt } from "./connector-autostart";
+import type { ConnectorSupervisor } from "./connector-supervisor";
+/**
+ * Bring persisted connectors back under the new hub's supervision.
+ *
+ * Called once per daemon boot, after the supervisor has adopted whatever
+ * survived the previous hub. Survivors still have to be *restarted* rather than
+ * left running: their hub client authenticated against the old hub's token and
+ * cannot re-authenticate against this one, so the process has to come back to
+ * attach to the new session.
+ *
+ * Spawning itself belongs to the supervisor, which is the single authority on
+ * how many processes may hold one connector's credentials.
+ */
+export declare function reconnectDaemonConnectors(log?: (message: string) => void, supervisor?: ConnectorSupervisor | undefined): Promise<ReconnectAttempt[]>;

package/dist/services/feature-flags/FeatureFlagsService.d.ts

@@ -0,0 +1,49 @@
+import type { BasicLogger, FeatureFlagPayload, FeatureFlagsAndPayloads, FeatureFlagsContext, IFeatureFlagsProvider, ITelemetryService } from "@cerebriline/shared";
+import { type FeatureFlag } from "@cerebriline/shared";
+type CacheInfo = {
+    updateTime: number;
+    userId: string | null;
+    flagsPayload?: FeatureFlagsAndPayloads;
+};
+export type FeatureFlagsCacheSnapshot = CacheInfo;
+export interface FeatureFlagsServiceOptions {
+    provider: IFeatureFlagsProvider;
+    telemetry?: ITelemetryService;
+    logger?: BasicLogger;
+    cacheTtlMs?: number;
+    cacheFilePath?: string;
+    persistentCacheMaxAgeMs?: number;
+    context?: FeatureFlagsContext;
+}
+export declare class FeatureFlagsService {
+    private readonly provider;
+    private readonly telemetry?;
+    private readonly logger?;
+    private readonly cacheTtlMs;
+    private readonly cacheFilePath?;
+    private readonly persistentCacheMaxAgeMs;
+    private context;
+    private cache;
+    private cacheInfo;
+    constructor(options: FeatureFlagsServiceOptions);
+    setContext(context: FeatureFlagsContext): void;
+    hydrateCache(snapshot: FeatureFlagsCacheSnapshot): void;
+    getCacheSnapshot(): FeatureFlagsCacheSnapshot;
+    poll(userId?: string | null): Promise<void>;
+    private hydrateFromPersistentCache;
+    private isFeatureFlagPayload;
+    private readPayloadRecord;
+    private readPersistentCache;
+    private writePersistentCache;
+    private getReturnedFlagKeys;
+    private rebuildCacheFromSnapshot;
+    private getFeatureFlag;
+    getBooleanFlagEnabled(flagName: FeatureFlag): boolean;
+    getFlagPayload(flagName: FeatureFlag): FeatureFlagPayload | undefined;
+    getProvider(): IFeatureFlagsProvider;
+    get enabled(): boolean;
+    getSettings(): import("@cerebriline/shared").FeatureFlagsSettings;
+    test(flagName: FeatureFlag, value: boolean): void;
+    dispose(): Promise<void>;
+}
+export {};

package/dist/services/feature-flags/index.d.ts

@@ -0,0 +1,2 @@
+export { FeatureFlagsService, type FeatureFlagsServiceOptions, } from "./FeatureFlagsService";
+export { NoOpFeatureFlagsProvider } from "./providers";

package/dist/services/feature-flags/posthog.d.ts

@@ -0,0 +1,24 @@
+import type { BasicLogger, FeatureFlagsAndPayloads, FeatureFlagsContext, FeatureFlagsSettings, IFeatureFlagsProvider } from "@cerebriline/shared";
+import { PostHog, type PostHogOptions } from "posthog-node";
+export interface PostHogFeatureFlagsProviderConfig {
+    logger?: BasicLogger;
+}
+export interface PostHogFeatureFlagsProviderOptions {
+    config: PostHogFeatureFlagsProviderConfig;
+    client: PostHog;
+}
+export declare function buildClinePostHogClient(apiKey: string, options?: PostHogOptions | undefined): PostHog;
+export declare class PostHogFeatureFlagsProvider implements IFeatureFlagsProvider {
+    private readonly client;
+    private readonly settings;
+    private readonly logger?;
+    constructor(options: PostHogFeatureFlagsProviderOptions);
+    getAllFlagsAndPayloads(options: {
+        flagKeys?: readonly string[];
+        context: FeatureFlagsContext;
+    }): Promise<FeatureFlagsAndPayloads | undefined>;
+    get enabled(): boolean;
+    getSettings(): FeatureFlagsSettings;
+    dispose(): Promise<void>;
+    private resolveDistinctId;
+}

package/dist/services/feature-flags/posthog.js

@@ -0,0 +1 @@
+import{PostHog as s}from"posthog-node";function a(e,t){return new s(e,{host:"https://data.cline.bot",...t})}class o{client;settings;logger;constructor(e){if(!e.client)throw Error("PostHog client is required for feature flags");this.logger=e.config.logger,this.settings={enabled:!0},this.client=e.client}async getAllFlagsAndPayloads(e){if(!this.enabled)return;let t=this.resolveDistinctId(e.context);if(!t)return this.logger?.log?.("PostHog feature flags requested without a distinct ID"),{};try{return await this.client.getAllFlagsAndPayloads(t,{flagKeys:e.flagKeys?[...e.flagKeys]:void 0})}catch(r){return this.logger?.error?.("Error getting PostHog feature flags",{error:r}),{}}}get enabled(){return this.settings.enabled}getSettings(){return{...this.settings}}async dispose(){try{await this.client.shutdown()}catch(e){this.logger?.error?.("Error shutting down PostHog feature flags client",{error:e})}}resolveDistinctId(e){return e?.distinctId?.trim()||e?.userId?.trim()||void 0}}export{a as buildClinePostHogClient,o as PostHogFeatureFlagsProvider};

package/dist/services/feature-flags/providers.d.ts

@@ -0,0 +1,7 @@
+import type { FeatureFlagsAndPayloads, FeatureFlagsSettings, IFeatureFlagsProvider } from "@cerebriline/shared";
+export declare class NoOpFeatureFlagsProvider implements IFeatureFlagsProvider {
+    getAllFlagsAndPayloads(): Promise<FeatureFlagsAndPayloads>;
+    enabled: boolean;
+    getSettings(): FeatureFlagsSettings;
+    dispose(): Promise<void>;
+}

package/dist/services/global-settings.d.ts

@@ -0,0 +1,113 @@
+import { type AgentConfig, type AgentTool, type ConfigurableModelToolName, type ITelemetryService, type ModelToolSettings } from "@cerebriline/shared";
+import { z } from "zod";
+declare const GlobalCompactionStrategySchema: z.ZodCatch<z.ZodEnum<{
+    basic: "basic";
+    agentic: "agentic";
+}>>;
+export type GlobalCompactionStrategy = z.infer<typeof GlobalCompactionStrategySchema>;
+/** Compaction strategy plus the "off" state surfaced by the CLI settings UI. */
+export type GlobalCompactionMode = GlobalCompactionStrategy | "off";
+declare const GlobalPlanActModeSchema: z.ZodEnum<{
+    plan: "plan";
+    act: "act";
+}>;
+export type GlobalPlanActMode = z.infer<typeof GlobalPlanActModeSchema>;
+export declare const GlobalSettingsSchema: z.ZodPipe<z.ZodObject<{
+    telemetryOptOut: z.ZodCatch<z.ZodDefault<z.ZodBoolean>>;
+    autoUpdateEnabled: z.ZodCatch<z.ZodDefault<z.ZodBoolean>>;
+    compactionStrategy: z.ZodOptional<z.ZodCatch<z.ZodEnum<{
+        basic: "basic";
+        agentic: "agentic";
+    }>>>;
+    compactionEnabled: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    planActMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+        plan: "plan";
+        act: "act";
+    }>>>;
+    toolAutoApprove: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    tuiTheme: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    disabledTools: z.ZodOptional<z.ZodPipe<z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>, z.ZodTransform<string[] | undefined, string[] | undefined>>>;
+    tools: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        web_search: "web_search";
+    }> & z.core.$partial, z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strip>>>;
+    disabledPlugins: z.ZodOptional<z.ZodPipe<z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>, z.ZodTransform<string[] | undefined, string[] | undefined>>>;
+    disabledAgentPlugins: z.ZodOptional<z.ZodPipe<z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>, z.ZodTransform<string[] | undefined, string[] | undefined>>>;
+}, z.core.$strip>, z.ZodTransform<{
+    telemetryOptOut: boolean;
+    autoUpdateEnabled: boolean;
+    compactionStrategy?: GlobalCompactionStrategy;
+    compactionEnabled?: boolean;
+    planActMode?: GlobalPlanActMode;
+    toolAutoApprove?: boolean;
+    tuiTheme?: string;
+    disabledTools?: string[];
+    tools?: ModelToolSettings;
+    disabledPlugins?: string[];
+    disabledAgentPlugins?: string[];
+}, {
+    telemetryOptOut: boolean;
+    autoUpdateEnabled: boolean;
+    compactionStrategy?: "basic" | "agentic" | undefined;
+    compactionEnabled?: boolean | undefined;
+    planActMode?: "plan" | "act" | undefined;
+    toolAutoApprove?: boolean | undefined;
+    tuiTheme?: string | undefined;
+    disabledTools?: string[] | undefined;
+    tools?: Partial<Record<"web_search", {
+        enabled: boolean;
+    }>> | undefined;
+    disabledPlugins?: string[] | undefined;
+    disabledAgentPlugins?: string[] | undefined;
+}>>;
+export type GlobalSettings = z.infer<typeof GlobalSettingsSchema>;
+export interface WriteGlobalSettingsOptions {
+    telemetry?: ITelemetryService;
+}
+export declare function readGlobalSettings(): GlobalSettings;
+export declare function writeGlobalSettings(settings: z.input<typeof GlobalSettingsSchema>, options?: WriteGlobalSettingsOptions): void;
+export declare function isTelemetryOptedOutGlobally(): boolean;
+export declare function setTelemetryOptOutGlobally(telemetryOptOut: boolean, options?: WriteGlobalSettingsOptions): void;
+export declare function isAutoUpdateEnabledGlobally(): boolean;
+export declare function setAutoUpdateEnabledGlobally(autoUpdateEnabled: boolean, options?: WriteGlobalSettingsOptions): void;
+export declare function readCompactionStrategyGlobally(): GlobalCompactionStrategy;
+export declare function setCompactionStrategyGlobally(compactionStrategy: GlobalCompactionStrategy): void;
+/**
+ * Returns the persisted compaction mode including the disabled state, or
+ * undefined when the user never chose one (callers apply their own default).
+ */
+export declare function readCompactionModeGlobally(): GlobalCompactionMode | undefined;
+/**
+ * Persists the full compaction mode. Selecting "off" keeps the previously
+ * chosen strategy so re-enabling compaction restores it.
+ */
+export declare function setCompactionModeGlobally(mode: GlobalCompactionMode): void;
+export declare function readPlanActModeGlobally(): GlobalPlanActMode | undefined;
+export declare function setPlanActModeGlobally(planActMode: GlobalPlanActMode): void;
+export declare function readToolAutoApproveGlobally(): boolean | undefined;
+/**
+ * Returns the persisted TUI theme id, or undefined when the user never chose
+ * one (callers apply their own default, typically terminal auto-detection).
+ */
+export declare function readTuiThemeGlobally(): string | undefined;
+export declare function setTuiThemeGlobally(tuiTheme: string): void;
+export declare function setToolAutoApproveGlobally(toolAutoApprove: boolean): void;
+export declare function resolveDisabledToolNames(disabledToolNames?: ReadonlyArray<string>): Set<string>;
+export declare function resolveDisabledPluginPaths(disabledPluginPaths?: ReadonlyArray<string>): Set<string>;
+export declare function resolveDisabledAgentPluginNames(disabledPluginNames?: ReadonlyArray<string>): Set<string>;
+export declare function isToolDisabledGlobally(toolName: string): boolean;
+export declare function resolveModelToolSettings(): ModelToolSettings;
+export declare function isModelToolEnabledGlobally(name: ConfigurableModelToolName): boolean;
+export declare function setModelToolEnabledGlobally(name: ConfigurableModelToolName, enabled: boolean): void;
+export declare function toggleDisabledTool(toolName: string): boolean;
+export declare function setDisabledTools(toolNames: ReadonlyArray<string>, disabledValue: boolean): void;
+export declare function setToolDisabledGlobally(toolName: string, disabled: boolean): boolean;
+export declare function isPluginDisabledGlobally(pluginPath: string): boolean;
+export declare function setDisabledPlugin(pluginPath: string, disabledValue: boolean): void;
+export declare function isAgentPluginDisabledGlobally(pluginName: string): boolean;
+export declare function setDisabledAgentPlugin(pluginName: string, disabledValue: boolean): void;
+export declare function filterDisabledPluginPaths(pluginPaths: ReadonlyArray<string>, disabledPluginPaths?: ReadonlyArray<string>): string[];
+export declare function filterDisabledTools<T extends Pick<AgentTool, "name">>(tools: ReadonlyArray<T>, disabledToolNames?: ReadonlyArray<string>): T[];
+export declare function filterExtensionToolRegistrations(extensions: AgentConfig["extensions"], disabledToolNames?: ReadonlyArray<string>): AgentConfig["extensions"];
+export {};

package/dist/services/llms/apihandler-agent-model-adapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Adapter: wrap a custom `ApiHandler` (from the `@cerebriline/llms` handler registry)
+ * as an `AgentModel` for the agent runtime.
+ *
+ * The agent runtime builds models via `createAgentModelFromConfig`, which goes
+ * straight to the gateway. Hosts can register provider handlers that need
+ * host-only dependencies (e.g. the VS Code `vscode.lm` API) via
+ * `registerHandler(providerId, factory)`. Those produce an `ApiHandler`
+ * (`createMessage` -> `ApiStreamChunk`), which this adapter converts into the
+ * `AgentModel` contract (`stream` -> `AgentModelEvent`).
+ *
+ * This is the inverse of the gateway's `toApiStreamChunk` in
+ * `@cerebriline/llms` `compat.ts`.
+ */
+import { type ApiHandler } from "@cerebriline/llms";
+import type { AgentModel } from "@cerebriline/shared";
+/**
+ * Resolves the `ApiHandler` to delegate to. A function is supported (and may be
+ * async) so handler construction can be deferred to the first `stream` call —
+ * which is required for providers registered via `registerAsyncHandler`.
+ */
+export type ApiHandlerSource = ApiHandler | (() => ApiHandler | Promise<ApiHandler>);
+/**
+ * Build an `AgentModel` that delegates to a registered `ApiHandler`.
+ */
+export declare function createAgentModelFromApiHandler(source: ApiHandlerSource): AgentModel;

package/dist/services/llms/cline-recommended-models.d.ts

@@ -0,0 +1,62 @@
+import { type ProviderModel } from "@cerebriline/shared";
+import { ProviderSettingsManager } from "../storage/provider-settings-manager";
+import type { ModelInfo } from "./provider-settings";
+export interface ClineRecommendedModel {
+    id: string;
+    /** Display-ready model name, resolved against the model catalog. */
+    name: string;
+    description: string;
+    tags: string[];
+}
+export interface ClineRecommendedModelsData {
+    recommended: ClineRecommendedModel[];
+    free: ClineRecommendedModel[];
+    clinePass: ClineRecommendedModel[];
+}
+type ModelsCatalog = Record<string, Record<string, ModelInfo>>;
+export interface FetchClineRecommendedModelsOptions {
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    providerSettingsManager?: Pick<ProviderSettingsManager, "getProviderSettings">;
+    timeoutMs?: number;
+    /**
+     * Loader for the live models catalog used to resolve display names.
+     * Defaults to the shared live-catalog cache; injectable for tests.
+     */
+    catalogLoader?: () => Promise<ModelsCatalog>;
+}
+export declare const FALLBACK_CLINE_RECOMMENDED_MODELS: ClineRecommendedModelsData;
+export declare function fetchClineRecommendedModels(options?: FetchClineRecommendedModelsOptions): Promise<ClineRecommendedModelsData>;
+/**
+ * `fetchClineRecommendedModels` with a shared in-memory cache, for callers on
+ * the model-list path (every picker open) where a per-call network round-trip
+ * — or its 5s offline timeout — is unacceptable. The bundled offline fallback
+ * is cached too: paying the timeout once per TTL beats paying it on every
+ * model list while offline, and a recovered network is picked up within the
+ * TTL.
+ */
+export declare function getCachedClineRecommendedModels(options?: FetchClineRecommendedModelsOptions): Promise<ClineRecommendedModelsData>;
+/**
+ * Synchronous, never-blocking view of the feed: the cached live data when
+ * fresh, otherwise the bundled fallback. For callers that build model lists
+ * eagerly and must not wait on the network (the provider catalog at startup),
+ * so even a cold boot renders tiered sections instead of a flat list. The
+ * async `getCachedClineRecommendedModels` path refreshes the cache, after
+ * which peeks serve live data for the TTL.
+ */
+export declare function peekClineRecommendedModels(): ClineRecommendedModelsData;
+export declare function resetClineRecommendedModelsCacheForTests(): void;
+/**
+ * Stamps recommended-feed tiers onto a provider's model list so clients can
+ * render Recommended/Free/Subscribed sections straight off `ProviderModel`
+ * instead of fetching and joining the feed themselves. Feed ids are matched
+ * through the Vercel/OpenRouter alias rules (the feed can spell a model
+ * differently from the catalog), with a fallback on the id's slug after "/"
+ * when that slug is unambiguous — the feed and the catalog can carry
+ * different vendor prefixes for the same model (`kwaipilot/kat-coder-pro`
+ * vs `cline-free/kat-coder-pro`), most visibly when the bundled fallback
+ * feed is stamped against a live-fetched catalog. Models the feed does not
+ * mention are returned unchanged; unknown providers pass through untouched.
+ */
+export declare function applyClineFeaturedModels(providerId: string, models: ProviderModel[], data: ClineRecommendedModelsData): ProviderModel[];
+export {};

package/dist/services/llms/configured-provider-registry.d.ts

@@ -0,0 +1,27 @@
+import type { ProviderConfig } from "./provider-settings";
+import type { BuiltInProviderSummary, CreateHandlerInput, ProviderConfigDefaults, ProviderSelectionConfig, RegisteredProviderSummary } from "./runtime-types";
+interface RegisterConfiguredProviderInput {
+    id: string;
+    models: readonly string[];
+    defaultModel?: string;
+    defaults?: ProviderConfigDefaults;
+}
+export declare function toBuiltInProviderSummary(input: {
+    collection: BuiltInProviderSummary["id"] extends string ? {
+        provider: Pick<import("@cerebriline/llms").ProviderInfo, "id" | "name" | "description" | "protocol" | "baseUrl" | "capabilities" | "env" | "defaultModelId">;
+        models: Record<string, unknown>;
+    } : never;
+}): BuiltInProviderSummary;
+export declare class ConfiguredProviderRegistry {
+    private readonly providers;
+    register(input: RegisterConfiguredProviderInput): void;
+    registerSelectionConfig(provider: ProviderSelectionConfig): void;
+    registerModel(providerId: string, modelId: string): void;
+    createHandlerConfig(input: CreateHandlerInput): ProviderConfig;
+    list(): RegisteredProviderSummary[];
+    getModels(providerId: string): string[];
+    hasProvider(providerId: string): boolean;
+    hasModel(providerId: string, modelId: string): boolean;
+    private require;
+}
+export {};

package/dist/services/llms/handler-factory.d.ts

@@ -0,0 +1,23 @@
+import type { AgentConfig, AgentModel, BasicLogger, ITelemetryService, ModelInfo } from "@cerebriline/shared";
+export declare function resolveKnownModelsFromConfig(config: AgentConfig): Record<string, ModelInfo> | undefined;
+export interface CreateAgentModelOptions {
+    /**
+     * Set by the caller that is running the conversation itself.
+     *
+     * The request path keeps process-wide records of what the last request cost
+     * and what capped it, and compaction reads them back; only the conversation
+     * may write them. This factory serves the agent loop *and* the machinery
+     * around it -- the CLI builds its image describer from the same call -- so
+     * the loop has to say so rather than the describer having to say it is not.
+     */
+    conversation?: boolean;
+    /**
+     * Force the auxiliary scheduling this config did not carry.
+     *
+     * A caller that builds its model from a session's config inherits that
+     * config's `providerConfig`, which is the conversation's; there is no place
+     * on it to say "but this call is not". This is that place.
+     */
+    auxiliary?: boolean;
+}
+export declare function createAgentModelFromConfig(config: AgentConfig, logger: BasicLogger | undefined, telemetry?: ITelemetryService, options?: CreateAgentModelOptions): AgentModel;

package/dist/services/llms/provider-defaults.d.ts

@@ -0,0 +1,36 @@
+/** biome-ignore-all lint/style/noNonNullAssertion: static */
+import * as Llms from "@cerebriline/llms";
+import type { ModelCatalogConfig, ModelInfo, ProviderCapability, ProviderConfig } from "./provider-settings";
+export interface BuiltInProviderManifest {
+    id: string;
+    baseUrl: string;
+    modelsSourceUrl?: string;
+    modelId: string;
+    knownModels?: Record<string, ModelInfo>;
+    capabilities?: Llms.CatalogProviderCapability[];
+    env?: readonly string[];
+    client: Llms.ProviderClient;
+    protocol?: Llms.ProviderProtocol;
+}
+export interface ProviderDefaults {
+    baseUrl?: string;
+    modelId: string;
+    knownModels?: Record<string, ModelInfo>;
+    capabilities?: ProviderCapability[];
+}
+export declare const DEFAULT_MODELS_CATALOG_URL = "https://models.dev/api.json";
+/**
+ * Whether a provider's model catalog comes from the customer's configured
+ * endpoint rather than a shared public catalog.
+ *
+ * Keep this derived from the fetcher registry so host consumers cannot drift
+ * from the providers whose live metadata is endpoint-specific.
+ */
+export declare function isPrivateModelCatalogProvider(providerId: string): boolean;
+export declare function clearPublicModelsCatalogCache(): void;
+export declare function getLiveModelsCatalog(options?: Pick<ModelCatalogConfig, "url" | "cacheTtlMs">): Promise<Record<string, Record<string, ModelInfo>>>;
+export declare function clearLiveModelsCatalogCache(url?: string): void;
+export declare function clearPrivateModelsCatalogCache(): void;
+export declare const OPENAI_COMPATIBLE_PROVIDERS: Record<string, ProviderDefaults>;
+export declare function getProviderConfig(providerId: string): ProviderDefaults | undefined;
+export declare function resolveProviderConfig(providerId: string, modelCatalog?: ModelCatalogConfig, config?: ProviderConfig): Promise<ProviderDefaults | undefined>;