@cerebriline/core 4.100.240

package/dist/hub/daemon/index.d.ts

@@ -0,0 +1,125 @@
+import { type HubServerProbeRecord } from "../discovery";
+import { type HubEndpointOverrides } from "../discovery/defaults";
+export declare const __test__: {
+    /** Retire attempts are module state keyed by URL; clear between cases. */
+    resetRetireAttempts(): void;
+};
+/**
+ * Reads the discovery record the npm postinstall set aside (see
+ * apps/cli/script/postinstall.mjs). Deliberately bypasses readHubDiscovery —
+ * the file is best-effort recovery metadata, not a live record — and stays
+ * synchronous so it adds no async boundary to the ensure flow.
+ *
+ * Exported for `cline doctor`, which must not mistake a shielded live hub for
+ * a stale daemon just because its record is set aside.
+ */
+export declare function readSupersededHubDiscovery(discoveryPath: string): {
+    url?: string;
+    authToken?: string;
+    pid?: number;
+} | undefined;
+/**
+ * Gracefully retire a discovered hub. Shared by every replacement path
+ * (detached ensure, in-process ensure) so retirement always means the same
+ * thing: drain first, then an authenticated shutdown, SIGTERM only as a
+ * last resort, and discovery cleared only once the hub is actually gone.
+ */
+export declare function retireDiscoveredHub(record: {
+    url: string;
+    authToken?: string;
+    pid?: number;
+}, discoveryPath: string): Promise<boolean>;
+export type HubRetirementOutcome = "reusable" | "retired" | "deferred_busy" | "failed";
+/**
+ * Whether the Hub is currently serving sessions, and so must not be shut down
+ * under them.
+ *
+ * Failing open (treating an unanswerable Hub as idle) preserves the existing
+ * replacement path for a Hub that is wedged or too old to answer the query;
+ * only a Hub that positively reports live sessions is spared.
+ */
+export declare function hubHasLiveSessions(record: Pick<HubServerProbeRecord, "url" | "authToken">): Promise<boolean>;
+export declare function spawnDetachedHubServer(workspaceRoot: string, endpoint?: HubEndpointOverrides): void;
+export declare function spawnDetachedHubServerWithRetry(workspaceRoot: string, endpoint?: HubEndpointOverrides): Promise<void>;
+export declare function prewarmDetachedHubServer(workspaceRoot: string, endpoint?: HubEndpointOverrides & {
+    allowPortFallback?: boolean;
+}): void;
+export interface DetachedHubResolution {
+    url: string;
+    authToken: string;
+}
+export declare function ensureDetachedHubServer(workspaceRoot: string, endpointOverrides?: HubEndpointOverrides & {
+    allowPortFallback?: boolean;
+}): Promise<DetachedHubResolution>;
+export interface UpgradeManagedHubOptions {
+    workspaceRoot?: string;
+    /**
+     * How long to wait, after draining, for the hub's live sessions to finish
+     * before replacing it (`force`) or giving up (`still_busy`).
+     */
+    waitForIdleMs?: number;
+    /**
+     * Replace the hub even if sessions are still live once the wait expires.
+     * Only set this on a user-consented path: those sessions die mid-turn.
+     * Honored only once the hub has accepted the drain - a busy hub that
+     * refused the drain is never replaced, because the drain is what protects
+     * work started during the wait window.
+     */
+    force?: boolean;
+    /** Recorded as the hub's drain reason, visible in `hub.status`. */
+    reason?: string;
+}
+export type UpgradeManagedHubOutcome = 
+/** The running older hub was retired and a current-build hub is up. */
+"replaced"
+/** No live hub was found; a current-build hub was started. */
+ | "started"
+/** The running hub already matches this build; nothing to do. */
+ | "already_current"
+/**
+ * The running hub is newer than (or unorderable against) this build.
+ * Replacing it would downgrade another install's hub and reopen the
+ * mutual-retire loop (#13145), so it is refused; updating this client is
+ * the fix.
+ */
+ | "hub_not_older"
+/** `force` was not set and sessions never finished - or the hub's
+ * activity could never be confirmed, which counts as busy here; the hub
+ * was un-drained and left running. */
+ | "still_busy";
+export interface UpgradeManagedHubResult {
+    outcome: UpgradeManagedHubOutcome;
+    url?: string;
+    authToken?: string;
+    /**
+     * Live sessions observed on the old hub at decision time: the sessions
+     * that were interrupted (`replaced`) or that kept it running
+     * (`still_busy`). Omitted when the hub never answered the activity query.
+     */
+    activeSessionCount?: number;
+}
+/**
+ * Replace the managed local hub with one running this build, on the user's
+ * explicit say-so. This is the deliberate counterpart to the automatic
+ * replacement in `ensureDetachedHubServer`, which defers while the older hub
+ * is serving sessions: drain first (the hub refuses new work while in-flight
+ * turns get `waitForIdleMs` to finish), then the shared graceful retire
+ * ladder, then a fresh daemon. Drain-first is a guarantee, not a courtesy:
+ * this function retires a hub only under an accepted drain, because the
+ * drain is the admission barrier that keeps any busy or idle reading true
+ * through the retire. A hub that refuses the drain fails the upgrade
+ * outright - `force` does not override that, and neither does an idle
+ * reading, which without the drain is only a snapshot that a newly admitted
+ * session could invalidate before the retire lands. (Such a hub is still
+ * replaced by the automatic ensure path once idle at the next client
+ * startup, the pre-existing recovery route for hubs too old to serve
+ * /drain.) Activity readings that fail are treated as unknown, not idle:
+ * they never shorten the wait window, and without `force` an unconfirmed
+ * hub is handed back un-drained rather than retired.
+ *
+ * Never replaces a hub this build is not strictly newer than - the build
+ * total order guarantees at most one side of any install pair can reach the
+ * retire step, which is what keeps two mixed installs from taking turns
+ * "upgrading" the hub to their own build.
+ */
+export declare function upgradeManagedHub(options?: UpgradeManagedHubOptions): Promise<UpgradeManagedHubResult>;

package/dist/hub/daemon/runtime-handlers.d.ts

@@ -0,0 +1,12 @@
+import type { ITelemetryService } from "@cerebriline/shared";
+import type { HubScheduleRuntimeHandlers, HubScheduleServiceOptions } from "../../cron/service/schedule-service";
+export interface CreateLocalHubScheduleRuntimeHandlersOptions extends Pick<HubScheduleServiceOptions, "logger"> {
+    /**
+     * Custom `fetch` implementation forwarded to the scheduler's internal
+     * `LocalRuntimeHost`. Used by the AI gateway providers for every
+     * scheduled session executed inside this hub process.
+     */
+    fetch?: typeof fetch;
+    telemetry?: ITelemetryService;
+}
+export declare function createLocalHubScheduleRuntimeHandlers(options?: CreateLocalHubScheduleRuntimeHandlersOptions): HubScheduleRuntimeHandlers;

package/dist/hub/daemon/shutdown-coordinator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Kept below the caller-side retirement wait so a current daemon exits through
+ * its own cleanup deadline before an older caller considers force retirement.
+ */
+export declare const HUB_DAEMON_SHUTDOWN_DEADLINE_MS = 2000;
+export interface HubDaemonShutdownRequest {
+    reason: string;
+    exitCode: number;
+}
+export type HubDaemonShutdownState = "idle" | "shutting_down" | "forced" | "finished";
+export interface HubDaemonShutdownCoordinatorOptions {
+    deadlineMs: number;
+    cleanup(): Promise<void>;
+    exit(code: number): void;
+    onCleanupError?(error: unknown): void;
+    onForcedExit?(request: HubDaemonShutdownRequest): void;
+}
+export interface HubDaemonShutdownCoordinator {
+    request(request: HubDaemonShutdownRequest): Promise<void>;
+    force(request: HubDaemonShutdownRequest): void;
+    getState(): HubDaemonShutdownState;
+}
+/**
+ * Owns the daemon's monotonic shutdown lifecycle.
+ *
+ * Every graceful trigger shares one cleanup promise. A later fatal trigger can
+ * raise the eventual exit code, but it cannot run cleanup twice. The deadline
+ * and an explicit second-signal path both use `force`, whose exit is also
+ * guarded so an injected test exit that returns cannot be called repeatedly.
+ */
+export declare function createHubDaemonShutdownCoordinator(options: HubDaemonShutdownCoordinatorOptions): HubDaemonShutdownCoordinator;

package/dist/hub/daemon/start-shared-server.d.ts

@@ -0,0 +1,18 @@
+import { type EnsuredHubWebSocketServerResult, type EnsureHubWebSocketServerOptions, type HubWebSocketServer, type HubWebSocketServerOptions } from "../server";
+export type HubServer = HubWebSocketServer;
+export type EnsureHubServerResult = EnsuredHubWebSocketServerResult;
+export interface StartHubServerOptions extends Omit<HubWebSocketServerOptions, "owner"> {
+}
+export interface EnsureHubServerOptions extends Omit<EnsureHubWebSocketServerOptions, "owner"> {
+}
+/**
+ * Start a hub WebSocket server bound to the default owner context for the
+ * current build environment. Callers that need a custom owner should invoke
+ * {@link startHubWebSocketServer} directly.
+ */
+export declare function startHubServer(options: StartHubServerOptions): Promise<HubServer>;
+/**
+ * Ensure a hub WebSocket server is running in the default owner context for the
+ * current build environment, reusing a compatible in-process instance when available.
+ */
+export declare function ensureHubServer(options: EnsureHubServerOptions): Promise<EnsureHubServerResult>;

package/dist/hub/daemon/telemetry.d.ts

@@ -0,0 +1,19 @@
+import { type ITelemetryService } from "@cerebriline/shared";
+export interface HubDaemonTelemetry {
+    readonly telemetry: ITelemetryService;
+    /** Flushes pending batches and disposes the underlying provider. */
+    dispose(): Promise<void>;
+}
+/**
+ * Telemetry for the detached hub daemon process.
+ *
+ * The daemon hosts the `LocalRuntimeHost` that emits `task.conversation_turn`
+ * and `task.tokens` for every hub-backed session, so without its own handle
+ * those events are dropped entirely - sessions bill on the backend while
+ * reporting nothing to OTel.
+ *
+ * The daemon is long-lived and frequently starts before the user logs in (or
+ * outlives an account switch), so the cached Cline account id is re-resolved
+ * periodically rather than only once at startup.
+ */
+export declare function createHubDaemonTelemetry(): HubDaemonTelemetry;

package/dist/hub/discovery/defaults.d.ts

@@ -0,0 +1,16 @@
+export declare const DEFAULT_HUB_HOST = "127.0.0.1";
+export declare const DEFAULT_HUB_PORT = 25463;
+export declare const DEFAULT_HUB_PATHNAME = "/hub";
+export interface HubEndpointOverrides {
+    host?: string;
+    port?: number;
+    pathname?: string;
+}
+export interface ResolveHubDefaultsOptions {
+    env?: NodeJS.ProcessEnv;
+    execArgv?: string[];
+}
+export declare function resolveDefaultHubHost(options?: ResolveHubDefaultsOptions): string;
+export declare function resolveDefaultHubPort(options?: ResolveHubDefaultsOptions): number;
+export declare function resolveDefaultHubPathname(options?: ResolveHubDefaultsOptions): string;
+export declare function resolveHubEndpointOptions(overrides?: HubEndpointOverrides, options?: ResolveHubDefaultsOptions): Required<HubEndpointOverrides>;

package/dist/hub/discovery/index.d.ts

@@ -0,0 +1,139 @@
+import { type HubCompatibilityResult, type HubProtocolMetadata } from "@cerebriline/shared";
+import { resolveClineDataDir, resolveClineDir } from "@cerebriline/shared/storage";
+export interface HubServerDiscoveryRecord {
+    hubId: string;
+    protocolVersion: string;
+    minClientProtocolVersion?: string;
+    maxClientProtocolVersion?: string;
+    capabilities?: readonly string[];
+    coreVersion?: string;
+    buildId?: string;
+    buildEpochMs?: number;
+    authToken: string;
+    host: string;
+    port: number;
+    url: string;
+    pid?: number;
+    startedAt: string;
+    updatedAt: string;
+}
+export type HubServerProbeRecord = {
+    protocolVersion: string;
+    minClientProtocolVersion?: string;
+    maxClientProtocolVersion?: string;
+    capabilities?: readonly string[];
+    coreVersion?: string;
+    buildId?: string;
+    buildEpochMs?: number;
+    host: string;
+    port: number;
+    url: string;
+    hubId?: string;
+    authToken?: string;
+    pid?: number;
+    startedAt?: string;
+    updatedAt?: string;
+};
+export interface HubOwnerContext {
+    ownerId: string;
+    discoveryPath: string;
+}
+export declare function createHubAuthToken(): string;
+export declare function resolveHubBuildId(): string;
+/**
+ * When this SDK build was produced, embedded at bundle time. Orders builds so
+ * managed-Hub handling can distinguish a newer daemon (attach and prompt the
+ * user to update) from a stale one (retire and replace). Undefined when
+ * running from unbundled sources, where no meaningful ordering exists.
+ */
+export declare function resolveHubBuildEpochMs(): number | undefined;
+export type ManagedHubCompatibilityResult = {
+    compatible: true;
+} | {
+    compatible: false;
+    reason: Exclude<HubCompatibilityResult, {
+        compatible: true;
+    }>["reason"] | "missing_build" | "build_mismatch";
+};
+/**
+ * Compatibility for a managed local Hub discovered through Cline's owner
+ * record. Unlike explicit endpoints, a managed Hub is code that this client
+ * is responsible for keeping current, so wire compatibility alone is not
+ * enough: reusing a daemon from another build would keep executing stale
+ * runtime, scheduler, connector, and command-handler code after an upgrade.
+ */
+export declare function getManagedHubCompatibility(record: HubProtocolMetadata & {
+    buildId?: string;
+}, expectedBuildId?: string): ManagedHubCompatibilityResult;
+export interface HubBuildIdentity {
+    buildId?: string;
+    buildEpochMs?: number;
+    coreVersion?: string;
+}
+/**
+ * Total order over Hub builds: negative when `a` is older than `b`, positive
+ * when newer, zero when the two are indistinguishable.
+ *
+ * The ordering is what keeps concurrent installations from replacing each
+ * other's daemons. A one-sided "may I reuse this?" predicate lets both sides
+ * answer no, and two clients then retire each other's Hub forever; a total
+ * order is antisymmetric by construction, so at most one side can ever decide
+ * to retire. Every tier below preserves that: a field decides only when both
+ * records carry it, and the final fallback is "equal", which means reuse.
+ *
+ * Tiers, in order: identical build, embedded build epoch, core release
+ * version, then build id as a deterministic tiebreak.
+ */
+export declare function compareHubBuilds(a: HubBuildIdentity, b: HubBuildIdentity): number;
+/**
+ * This build's own identity, in the same shape a daemon publishes into its
+ * discovery record.
+ *
+ * Self and peer identities must be built from the same fields. Enriching only
+ * the local side - filling in a `coreVersion` the wire record can omit, say -
+ * makes a build's identity depend on which role it is playing, and two
+ * installations then decide the comparison on different tiers and each
+ * conclude that it is the newer one. Callers that need a synthetic identity
+ * pass it verbatim rather than layering overrides onto this.
+ */
+export declare function resolveHubBuildIdentity(): HubBuildIdentity;
+/**
+ * Whether a client may keep using a managed local Hub instead of retiring it.
+ *
+ * A Hub is retired only when this client's build is *strictly newer* by
+ * {@link compareHubBuilds}. Same build, newer Hub, and indistinguishable
+ * builds all attach over the compatible wire protocol and let the
+ * build-mismatch watcher prompt the user to update. Because the decision is
+ * derived from a total order, two installations can never retire each other.
+ *
+ * Genuine protocol incompatibility is unaffected: those Hubs cannot be spoken
+ * to at all and are still replaced.
+ */
+export declare function isManagedHubReusable(record: HubProtocolMetadata & HubBuildIdentity, options?: {
+    self?: HubBuildIdentity;
+}): boolean;
+export declare function resolveHubOwnerContext(ownerBasis?: string): HubOwnerContext;
+export declare function createInMemoryHubOwnerContext(label?: string): HubOwnerContext;
+export declare function readHubDiscovery(discoveryPath: string): Promise<HubServerDiscoveryRecord | undefined>;
+export interface WriteHubDiscoveryOptions {
+    /**
+     * Runs synchronously immediately before the record becomes visible to
+     * readers (the atomic rename). A server marks itself ready here so that a
+     * reader who finds the record can never reach a hub that still answers
+     * "Starting": the directory fsync and mutation-lock teardown that follow
+     * the rename are not part of the readiness window.
+     */
+    beforePublish?: () => void;
+}
+export declare function writeHubDiscovery(discoveryPath: string, record: HubServerDiscoveryRecord, options?: WriteHubDiscoveryOptions): Promise<void>;
+export declare function clearHubDiscovery(discoveryPath: string): Promise<void>;
+export declare function clearHubDiscoveryIfOwned(discoveryPath: string, hubId: string): Promise<boolean>;
+export declare function withHubStartupLock<T>(discoveryPath: string, callback: () => Promise<T>): Promise<T>;
+export declare function probeHubServer(url: string, options?: {
+    authToken?: string;
+}): Promise<HubServerProbeRecord | undefined>;
+export declare function createHubServerUrl(host: string, port: number, pathname?: string): string;
+export declare function toHubHealthUrl(wsUrl: string): string;
+export declare function toHubStatusUrl(wsUrl: string): string;
+export declare function isDiscoveryFilePresent(pathname: string): boolean;
+export { resolveClineDataDir, resolveClineDir };

package/dist/hub/discovery/instance-lock.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OS-backed exclusive Hub instance lock.
+ *
+ * Authority over a Hub owner context (the discovery path) is an
+ * operating-system exclusive lock, not a PID file, not a heartbeat, and not
+ * build arbitration: the lock is a SQLite database held inside a
+ * never-committed `BEGIN EXCLUSIVE` transaction, which SQLite maps onto OS
+ * file locks. The kernel releases the lock the instant the holding process
+ * dies — crashed holders cannot leak ownership, and a live holder cannot be
+ * displaced by deleting a file.
+ *
+ * A process that fails to acquire the lock must connect to the running Hub
+ * or diagnose — never kill it and never bind another endpoint on its own.
+ * This makes the historical mutual-retire loop (two installs SIGTERMing each
+ * other's daemon, #13145/#13230) structurally impossible: at most one live
+ * Hub can exist per owner context, enforced by the OS before either process
+ * gets a chance to disagree.
+ *
+ * The startup-lock directory (`<discoveryPath>.lock`, see `withHubLock`)
+ * remains a short-lived mutex around discovery reads/writes; this lock is a
+ * different thing — it is held for the entire lifetime of the serving Hub.
+ */
+/** Exit code for a daemon that lost the singleton race: diagnose, never replace. */
+export declare const HUB_LOCK_HELD_EXIT_CODE = 3;
+/** The lock is held by another live Hub process (or connection). */
+export declare class HubLockHeldError extends Error {
+    readonly lockFile: string;
+    constructor(lockFile: string);
+}
+export declare function isHubLockHeldError(error: unknown): error is HubLockHeldError;
+/** The lock file that guards one owner context (derived from its discovery path). */
+export declare function resolveHubInstanceLockPath(discoveryPath: string): string;
+export declare class HubInstanceLock {
+    private db;
+    readonly lockFile: string;
+    private constructor();
+    get held(): boolean;
+    /** Release the lock (process exit releases it too, via the OS). */
+    release(): void;
+    /**
+     * Attempt to take exclusive ownership of a Hub owner context. Throws
+     * `HubLockHeldError` when another live process holds it.
+     *
+     * Only a positively held lock (SQLITE_BUSY/LOCKED) refuses startup. Any
+     * other failure — SQLite unavailable in this runtime, an unwritable lock
+     * directory — degrades to an unheld lock (`held === false`) and the Hub
+     * starts without singleton enforcement, matching how the event log and
+     * run queue already degrade rather than making SQLite a hard requirement.
+     */
+    static acquire(lockFile: string): HubInstanceLock;
+}

package/dist/hub/discovery/workspace.d.ts

@@ -0,0 +1,13 @@
+import { type HubOwnerContext } from ".";
+export declare function resolveWorkspaceHubOwnerContext(workspaceRoot: string): HubOwnerContext;
+/**
+ * Development builds change on every compile, so a single shared owner record
+ * puts every checkout and every rebuild in contention for one daemon - and the
+ * loser of that contention gets shut down mid-session. Scoping the owner by
+ * build id lets differing dev builds run their own Hub side by side instead of
+ * arbitrating over one. Production keeps a single owner (see
+ * {@link resolveProductionHubOwnerContext}), where the singleton matters and
+ * builds are ordered.
+ */
+export declare function resolveSharedHubOwnerContext(label?: string): HubOwnerContext;
+export declare function resolveProductionHubOwnerContext(): HubOwnerContext;

package/dist/hub/index.d.ts

@@ -0,0 +1,38 @@
+export type { ITelemetryService } from "@cerebriline/shared";
+export { HubScheduleCommandService } from "../cron/service/schedule-command-service";
+export { HubScheduleService } from "../cron/service/schedule-service";
+export { type AgentScheduleServiceApi, executeScheduleOperation, type ScheduledTaskInput, ScheduledTaskInputSchema, type ScheduledTaskResult, type ScheduleTaskOperationOptions, } from "../cron/service/schedule-tool";
+/**
+ * Re-exported so detached hub daemon entry points (e.g. the VS Code
+ * `hub-daemon.ts` companion process) can construct a telemetry service
+ * from a single `@cerebriline/core/hub` import. The hub daemon is the
+ * canonical owner of telemetry forwarding for sessions executed inside
+ * the detached process, so the factory belongs on the hub surface even
+ * though its implementation lives under `services/telemetry`.
+ *
+ * `createConfiguredTelemetryHandle` is the preferred entry point for
+ * hosts: it bundles the telemetry service together with the canonical
+ * `flush`/`dispose` closures so detached daemons, the VS Code extension,
+ * and the CLI can share one implementation instead of each
+ * re-deriving the same lifecycle plumbing.
+ */
+export { type ConfiguredTelemetryHandle, type CreateOpenTelemetryTelemetryServiceOptions, createConfiguredTelemetryHandle, createConfiguredTelemetryService, } from "../services/telemetry/OpenTelemetryProvider";
+export { type CreateTasksToolOptions, createTasksPromptExtension, createTasksTool, TASKS_SYSTEM_PROMPT_RULE, TASKS_TOOL_NAME, type TasksToolInput, TasksToolInputSchema, type TasksToolResult, } from "../tasks/task-tool";
+export * from "./client";
+export * from "./client/connect";
+export * from "./client/managed-hub-build-watcher";
+export * from "./client/session-client";
+export * from "./client/ui-client";
+export * from "./daemon";
+export * from "./daemon/runtime-handlers";
+export * from "./daemon/start-shared-server";
+export * from "./discovery";
+export * from "./discovery/defaults";
+export * from "./discovery/instance-lock";
+export * from "./discovery/workspace";
+export * from "./server";
+export * from "./server/browser-websocket";
+export * from "./server/command-transport";
+export * from "./server/hub-event-log";
+export * from "./server/hub-run-queue";
+export * from "./server/native-transport";