@cerebriline/core 4.100.240

package/dist/hooks/subprocess.d.ts

@@ -0,0 +1,74 @@
+import { type AgentAbortHookPayload, type AgentEndHookPayload, type AgentErrorHookPayload, type AgentHooks, type AgentResumeHookPayload, type AgentStartHookPayload, type HookEventName, HookEventNameSchema, type HookEventPayload, type HookEventPayloadBase, HookEventPayloadSchema, type HookSessionContextProvider, type PostToolUseData, type PreCompactData, type PreCompactHookPayload, type PreToolUseData, type PromptSubmitHookPayload, parseHookEventPayload, type SessionShutdownHookPayload, type TaskCancelData, type TaskCompleteData, type TaskResumeData, type TaskStartData, type ToolCallHookPayload, type ToolResultHookPayload, type UserPromptSubmitData, type WorkspaceInfo } from "@cerebriline/shared";
+import { z } from "zod";
+import { type RunSubprocessEventResult } from "./subprocess-runner";
+/**
+ * Maximum size for a hook's injected context (`contextModification`), matching
+ * the legacy extension's cap. Prevents a hook from overflowing the prompt.
+ */
+export declare const MAX_HOOK_CONTEXT_SIZE = 50000;
+export declare function truncateHookContext(context: string | undefined): string | undefined;
+export interface HookOutput {
+    contextModification: string;
+    cancel: boolean;
+    review?: boolean;
+    errorMessage: string;
+}
+export declare const HookOutputSchema: z.ZodObject<{
+    contextModification: z.ZodOptional<z.ZodString>;
+    cancel: z.ZodOptional<z.ZodBoolean>;
+    review: z.ZodOptional<z.ZodBoolean>;
+    errorMessage: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodString>;
+    overrideInput: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+export { HookEventNameSchema, HookEventPayloadSchema, parseHookEventPayload };
+export type { AgentAbortHookPayload, AgentEndHookPayload, AgentErrorHookPayload, AgentResumeHookPayload, AgentStartHookPayload, HookEventName, HookEventPayload, HookEventPayloadBase, PostToolUseData, PreCompactData, PreCompactHookPayload, PreToolUseData, PromptSubmitHookPayload, SessionShutdownHookPayload, TaskCancelData, TaskCompleteData, TaskResumeData, TaskStartData, ToolCallHookPayload, ToolResultHookPayload, UserPromptSubmitData, };
+export interface RunHookOptions {
+    command?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    detached?: boolean;
+    timeoutMs?: number;
+    onSpawn?: (event: {
+        command: string[];
+        pid?: number;
+        detached: boolean;
+    }) => void;
+}
+export type RunHookResult = RunSubprocessEventResult;
+export declare function runHook(payload: HookEventPayload, options?: RunHookOptions): Promise<RunHookResult | undefined>;
+export interface SubprocessHooksOptions {
+    command?: string[];
+    cwd?: string;
+    /**
+     * Structured workspace and git metadata forwarded into every hook payload
+     * as `workspaceInfo`. Obtained from `generateWorkspaceInfo` at session
+     * startup and passed here so hook scripts can inspect branch, commit, and
+     * remote without running their own `git` commands.
+     */
+    workspaceInfo?: WorkspaceInfo;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    onDispatchError?: (error: Error, payload: HookEventPayload) => void;
+    onDispatch?: (event: {
+        payload: HookEventPayload;
+        result?: RunHookResult;
+        detached: boolean;
+    }) => void;
+    onSpawn?: (event: {
+        command: string[];
+        pid?: number;
+        detached: boolean;
+    }) => void;
+    sessionContext?: HookSessionContextProvider;
+}
+export interface SubprocessHookControl {
+    hooks: AgentHooks;
+    shutdown: (ctx: {
+        agentId: string;
+        conversationId: string;
+        parentAgentId: string | null;
+        reason?: string;
+    }) => Promise<void>;
+}
+export declare function createSubprocessHooks(options?: SubprocessHooksOptions): SubprocessHookControl;

package/dist/hub/client/connect.d.ts

@@ -0,0 +1,14 @@
+import type { HubCommandEnvelope, HubReplyEnvelope } from "@cerebriline/shared";
+import { type HubEndpointOverrides } from "../discovery/defaults";
+export interface HubConnection {
+    send(envelope: HubCommandEnvelope): Promise<HubReplyEnvelope>;
+    close(): void;
+}
+export interface HubCommandRequest extends Omit<HubCommandEnvelope, "version" | "clientId"> {
+    version?: HubCommandEnvelope["version"];
+    clientId?: string;
+}
+export declare function resolveHubUrl(overrides?: HubEndpointOverrides): Promise<string>;
+export declare function connectToHub(url: string): Promise<HubConnection>;
+export declare function probeHubConnection(url: string): Promise<boolean>;
+export declare function sendHubCommand(overrides: HubEndpointOverrides, envelope: HubCommandRequest): Promise<HubReplyEnvelope>;

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

@@ -0,0 +1,146 @@
+import { type HubClientRegistration, type HubCommandEnvelope, type HubEventEnvelope, type HubReplyEnvelope } from "@cerebriline/shared";
+import { type HubOwnerContext } from "../discovery";
+export interface HubClientOptions {
+    url: string;
+    clientId?: string;
+    clientType?: string;
+    displayName?: string;
+    workspaceRoot?: string;
+    cwd?: string;
+    authToken?: string;
+    capabilities?: HubClientRegistration["capabilities"];
+}
+export interface LocalHubResolutionOptions {
+    endpoint?: string;
+    strategy?: "prefer-hub" | "require-hub";
+    workspaceRoot?: string;
+    cwd?: string;
+}
+export type HubTransportErrorCode = "hub_connect_timeout" | "hub_connect_failed" | "hub_connection_closed" | "hub_connection_not_open";
+export declare class HubTransportError extends Error {
+    readonly code: HubTransportErrorCode;
+    readonly details?: {
+        closeCode?: number;
+        closeReason?: string;
+    } | undefined;
+    constructor(code: HubTransportErrorCode, message: string, details?: {
+        closeCode?: number;
+        closeReason?: string;
+    } | undefined);
+}
+export declare function isHubReconnectableTransportError(error: unknown): error is HubTransportError;
+export declare class HubCommandError extends Error {
+    readonly command: HubCommandEnvelope["command"];
+    readonly code: string | undefined;
+    constructor(command: HubCommandEnvelope["command"], code: string | undefined, message: string);
+}
+export declare function isHubCommandTimeoutError(error: unknown, command?: HubCommandEnvelope["command"]): boolean;
+export declare function rememberRecoverableLocalHubUrl(url: string, authToken?: string): string;
+export declare class NodeHubClient {
+    private readonly options;
+    private socket;
+    private connectPromise;
+    private readonly clientId;
+    private currentUrl;
+    private recoveryPromise;
+    private readonly pendingReplies;
+    private readonly listeners;
+    private readonly subscriptionCounts;
+    /**
+     * Highest durable event sequence observed per subscription key. Sent as
+     * `sinceSequence` when a subscription frame is (re)issued, so a hub with a
+     * durable event log replays exactly what this client missed while
+     * disconnected. Hubs without a log ignore the cursor (live-only, the
+     * legacy behavior).
+     */
+    private readonly lastEventSequenceByKey;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private closedByClient;
+    private lastCloseError;
+    private sawSocketClose;
+    private registered;
+    private capabilities;
+    constructor(options: HubClientOptions);
+    getClientId(): string;
+    getUrl(): string;
+    isConnected(): boolean;
+    getConnectionError(): HubTransportError | null;
+    updateCapabilities(capabilities: NonNullable<HubClientRegistration["capabilities"]>): Promise<void>;
+    connect(): Promise<void>;
+    subscribe(listener: (event: HubEventEnvelope) => void, options?: {
+        sessionId?: string;
+    }): () => void;
+    command(command: HubCommandEnvelope["command"], payload?: Record<string, unknown>, sessionId?: string, options?: {
+        timeoutMs?: number | null;
+    }): Promise<HubReplyEnvelope>;
+    private commandOnce;
+    private recoverLocalHubTransport;
+    private hasActiveSubscriptions;
+    private clearReconnectTimer;
+    private scheduleReconnect;
+    private reconnectSubscribedTransport;
+    close(): void;
+    dispose(): Promise<void>;
+    private sendFrame;
+    private sendSubscriptionFrame;
+    private adjustSubscriptionCount;
+    private subscriptionKeyForSessionId;
+    private subscriptionSessionIdFromKey;
+    private handleFrame;
+}
+export declare function normalizeHubWebSocketUrl(url: string): string;
+export declare function verifyHubConnection(url: string, options?: Pick<HubClientOptions, "workspaceRoot" | "cwd" | "authToken">): Promise<boolean>;
+export interface HubSessionActivity {
+    /** Sessions with at least one live participant attached. */
+    activeSessionCount: number;
+    /** Distinct client ids attached to those sessions. */
+    participantClientCount: number;
+}
+/**
+ * Summarize live activity from a `session.list` payload. A session counts as
+ * active only while a client is attached to it - the one signal that cannot
+ * go stale, because participants are live socket subscriptions the hub drops
+ * the moment a client's connection closes.
+ *
+ * Deliberately NOT based on session status: a client that dies without
+ * stopping its session leaves the hub-side runtime behind in a non-terminal
+ * status forever, and counting those "ghost" sessions as busy pins an
+ * outdated hub as "serving sessions" until the machine reboots. The cost of
+ * ignoring status is that a participant-less background run executing at the
+ * exact moment of a hub swap dies with the old hub - rare, and its next
+ * scheduled tick runs normally on the replacement.
+ */
+export declare function summarizeHubSessionActivity(payload: unknown): HubSessionActivity;
+export declare function hasActiveHubSessions(payload: unknown): boolean;
+/**
+ * Ask a hub how much live work it is serving. Throws when the hub cannot
+ * answer (unreachable, auth rejected, or too old to serve `session.list`),
+ * because the safe default points in opposite directions per caller: a
+ * replacement path treats an unanswerable hub as idle and retires it, while
+ * a recovery path treats it as busy and leaves it alone. Callers pick their
+ * own fallback instead of inheriting a hidden one.
+ */
+export declare function queryHubSessionActivity(url: string, authToken?: string, options?: Pick<HubClientOptions, "workspaceRoot" | "cwd">): Promise<HubSessionActivity>;
+export declare function localHubHasNoActiveSessions(url: string, authToken?: string, options?: Pick<HubClientOptions, "workspaceRoot" | "cwd">): Promise<boolean>;
+export declare function resolveCompatibleLocalHubUrl(options?: LocalHubResolutionOptions): Promise<string | undefined>;
+export declare function ensureCompatibleLocalHubUrl(options?: LocalHubResolutionOptions): Promise<string | undefined>;
+/**
+ * Ask a hub to stop admitting new mutating work (sessions, runs) while its
+ * accepted work finishes. Best-effort: pre-drain hubs answer 404 and the
+ * caller proceeds without it.
+ *
+ * Pass `{ off: true }` to lift a drain (`POST /drain?off`): an aborted
+ * upgrade must be able to hand the hub back instead of leaving it refusing
+ * work until a restart.
+ */
+export declare function requestHubDrain(url: string, authToken?: string, reason?: string, options?: {
+    off?: boolean;
+}): Promise<boolean>;
+export declare function requestHubShutdown(url: string, authToken?: string): Promise<boolean>;
+export declare function stopLocalHubServerGracefully(owner?: HubOwnerContext): Promise<boolean>;
+export declare function restartLocalHubIfIdleAfterStartupTimeout(options: {
+    url: string;
+    workspaceRoot?: string;
+    cwd?: string;
+}): Promise<string | undefined>;

package/dist/hub/client/managed-hub-build-watcher.d.ts

@@ -0,0 +1,62 @@
+export interface ManagedHubBuildMismatchEvent {
+    /** WebSocket URL of the live managed Hub that does not match this build. */
+    url: string;
+    /**
+     * Why client and Hub disagree:
+     * - `build_mismatch`: the running Hub is a newer build this client stays
+     *   attached to, and updating this client resolves it.
+     * - `unsupported_protocol`: this client cannot speak the Hub's protocol.
+     * - `outdated_hub`: this client is the newer build, but the running Hub was
+     *   left in place because it is still serving sessions. Nothing to install;
+     *   the Hub is replaced once those sessions end.
+     */
+    reason: "unsupported_protocol" | "build_mismatch" | "outdated_hub";
+    /** Build identity reported by the running Hub, when it reports one. */
+    hubBuildId?: string;
+    /** Core package version reported by the running Hub. */
+    hubCoreVersion?: string;
+    /** Build identity this client expects a managed Hub to match. */
+    expectedBuildId: string;
+    /**
+     * Sessions with live participants on the Hub (best-effort, `outdated_hub`
+     * only): the work that replacing the Hub would interrupt. Unset when the
+     * Hub cannot answer the query.
+     */
+    activeSessionCount?: number;
+    /** Distinct clients attached to those sessions (best-effort, `outdated_hub` only). */
+    participantClientCount?: number;
+}
+/**
+ * Probe the managed local Hub once and report whether a live Hub is running
+ * a build this client cannot manage. Returns `undefined` when there is no
+ * discovery record, the recorded Hub is unreachable, a Hub startup
+ * transaction is in flight (another client may be mid-replacement), or the
+ * running Hub matches this build.
+ *
+ * A mismatch means another Cline installation replaced the shared Hub with a
+ * different build (for example, the CLI was updated while the desktop app
+ * kept running). This client can keep talking to it over the compatible wire
+ * protocol, but it should prompt the user to update and restart so client
+ * and Hub run the same code again.
+ */
+export declare function checkManagedHubBuildMismatch(): Promise<ManagedHubBuildMismatchEvent | undefined>;
+export interface WatchManagedHubBuildOptions {
+    onMismatch: (event: ManagedHubBuildMismatchEvent) => void;
+    intervalMs?: number;
+}
+/**
+ * Periodically watch the managed local Hub for a build-identity mismatch and
+ * invoke `onMismatch` when another Cline installation has replaced the Hub
+ * with a different build. Fires once per observed Hub build (it will fire
+ * again only if the Hub changes to yet another mismatched build after a
+ * compatible one was seen, or a different mismatch reason appears).
+ *
+ * Start this only for managed Hub usage. Hosts configured with an explicit
+ * Hub endpoint keep protocol-only compatibility and must not show update
+ * prompts, so the watcher refuses to start when `CLINE_HUB_PORT` is set.
+ * The first check runs after one interval so app startup (which may itself
+ * be replacing a stale Hub) has settled.
+ *
+ * Returns a stop function.
+ */
+export declare function watchManagedHubBuildMismatch(options: WatchManagedHubBuildOptions): () => void;

package/dist/hub/client/session-client.d.ts

@@ -0,0 +1,138 @@
+import type * as LlmsProviders from "@cerebriline/llms";
+import type { AgendaAutomationPolicy, AgendaTaskListInput, AgendaTaskRecord, AgendaTaskRunRecord, ChatRunTurnRequest, ChatStartSessionRequest, ChatStartSessionResponse, ChatTurnResult, HubSessionSearchHit, HubTaskCreateInput, HubTaskUpdateInput, TeamProgressProjectionEvent } from "@cerebriline/shared";
+import type { CheckpointEntry } from "../../hooks/checkpoint-hooks";
+type ScheduleClientRecord = Record<string, unknown> & {
+    metadata?: Record<string, unknown>;
+};
+export interface HubSessionClientOptions {
+    address: string;
+    authToken?: string;
+    clientId?: string;
+    clientType?: string;
+    displayName?: string;
+    workspaceRoot?: string;
+    cwd?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface HubSessionRow {
+    sessionId: string;
+    parentSessionId?: string;
+    /** Hub runtime status when the server provided one. */
+    status?: string;
+    metadata?: Record<string, unknown>;
+    messagesPath?: string;
+}
+export interface HubStreamEvent {
+    sessionId: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+}
+export interface HubRestoreRequest {
+    sessionId: string;
+    checkpointRunCount: number;
+    config?: ChatStartSessionRequest;
+    restore?: {
+        messages?: boolean;
+        workspace?: boolean;
+        omitCheckpointMessageFromSession?: boolean;
+    };
+}
+export interface HubRestoreResponse {
+    sessionId?: string;
+    startResult?: {
+        sessionId: string;
+        manifestPath: string;
+        messagesPath: string;
+    };
+    messages?: LlmsProviders.MessageWithMetadata[];
+    checkpoint: CheckpointEntry;
+}
+export interface HubEventStreamHandlers {
+    onEvent?: (event: HubStreamEvent) => void;
+    onError?: (error: Error) => void;
+}
+export interface HubTeamProgressHandlers {
+    onProjection?: (event: TeamProgressProjectionEvent) => void;
+    onError?: (error: Error) => void;
+}
+export declare class HubSessionClient {
+    private readonly options;
+    private readonly client;
+    private metadataApplied;
+    constructor(options: HubSessionClientOptions);
+    private ensureMetadataApplied;
+    connect(): Promise<void>;
+    private taskCommand;
+    close(): void;
+    dispose(): Promise<void>;
+    startRuntimeSession(request: ChatStartSessionRequest): Promise<ChatStartSessionResponse>;
+    sendRuntimeSession(sessionId: string, request: ChatRunTurnRequest, options?: {
+        timeoutMs?: number | null;
+    }): Promise<{
+        result?: ChatTurnResult;
+    }>;
+    stopRuntimeSession(sessionId: string): Promise<{
+        applied: boolean;
+    }>;
+    abortRuntimeSession(sessionId: string): Promise<{
+        applied: boolean;
+    }>;
+    updateSession(input: {
+        sessionId: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        updated: boolean;
+    }>;
+    getSession(sessionId: string): Promise<HubSessionRow | undefined>;
+    readMessages(sessionId: string): Promise<LlmsProviders.MessageWithMetadata[]>;
+    restore(input: HubRestoreRequest): Promise<HubRestoreResponse>;
+    listSessions(input?: {
+        limit?: number;
+    }): Promise<HubSessionRow[]>;
+    searchSessions(input: {
+        query: string;
+        limit?: number;
+        workspaceRoot?: string;
+    }): Promise<HubSessionSearchHit[]>;
+    deleteSession(sessionId: string, deleteCheckpointRefs?: boolean): Promise<boolean>;
+    respondToolApproval(input: {
+        approvalId: string;
+        approved: boolean;
+        reason?: string;
+        responderClientId?: string;
+    }): Promise<void>;
+    streamEvents(input: {
+        clientId?: string;
+        sessionIds?: string[];
+    }, handlers: HubEventStreamHandlers): () => void;
+    streamTeamProgress(_input: {
+        clientId?: string;
+    }, handlers: HubTeamProgressHandlers): () => void;
+    createSchedule(input: Record<string, unknown>): Promise<ScheduleClientRecord | undefined>;
+    listSchedules(_input?: {
+        limit?: number;
+    }): Promise<ScheduleClientRecord[]>;
+    getSchedule(scheduleId: string): Promise<ScheduleClientRecord | undefined>;
+    updateSchedule(scheduleId: string, input: Record<string, unknown>): Promise<ScheduleClientRecord | undefined>;
+    pauseSchedule(scheduleId: string): Promise<ScheduleClientRecord | undefined>;
+    resumeSchedule(scheduleId: string): Promise<ScheduleClientRecord | undefined>;
+    deleteSchedule(scheduleId: string): Promise<boolean>;
+    triggerScheduleNow(scheduleId: string): Promise<Record<string, unknown> | undefined>;
+    listScheduleExecutions(scheduleId: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    getScheduleStats(): Promise<Record<string, unknown> | undefined>;
+    getActiveScheduledExecutions(): Promise<Array<Record<string, unknown>>>;
+    getUpcomingScheduledRuns(limit?: number): Promise<Array<Record<string, unknown>>>;
+    createTask(input: HubTaskCreateInput): Promise<AgendaTaskRecord>;
+    listTasks(input?: AgendaTaskListInput): Promise<AgendaTaskRecord[]>;
+    getTask(taskId: string): Promise<AgendaTaskRecord | undefined>;
+    updateTask(input: HubTaskUpdateInput): Promise<AgendaTaskRecord>;
+    approveTask(taskId: string, expectedRevision: number): Promise<AgendaTaskRecord>;
+    cancelTask(taskId: string, expectedRevision: number, reason?: string): Promise<AgendaTaskRecord>;
+    runTask(taskId: string, expectedRevision: number): Promise<{
+        task: AgendaTaskRecord;
+        run?: AgendaTaskRunRecord;
+    }>;
+    getTaskAutomation(): Promise<AgendaAutomationPolicy>;
+    setTaskAutomation(policy: Omit<AgendaAutomationPolicy, "updatedAt">): Promise<AgendaAutomationPolicy>;
+}
+export {};

package/dist/hub/client/ui-client.d.ts

@@ -0,0 +1,52 @@
+import type { HubClientRecord, HubSessionSearchHit, HubUINotifyPayload, HubUIShowWindowPayload, SessionRecord } from "@cerebriline/shared";
+import type { CoreSettingsMutationResult, CoreSettingsToggleInput } from "../../settings";
+export interface HubUIClientOptions {
+    address: string;
+    authToken?: string;
+    clientId?: string;
+    clientType?: string;
+    displayName?: string;
+}
+/**
+ * A lightweight hub client for UI/notification concerns.
+ * Used by the menu bar app and other UI clients to send/receive
+ * UI events (notifications, show window, client tracking).
+ */
+export declare class HubUIClient {
+    private readonly client;
+    constructor(options: HubUIClientOptions);
+    connect(): Promise<void>;
+    close(): void;
+    dispose(): Promise<void>;
+    getClientId(): string;
+    /**
+     * Send a notification request to the hub.
+     * The hub will broadcast a "ui.notify" event to all subscribers (e.g. the menu bar app).
+     */
+    sendNotify(payload: HubUINotifyPayload): Promise<void>;
+    /**
+     * Request the hub to broadcast a "ui.show_window" event to all subscribers.
+     */
+    sendShowWindow(payload?: HubUIShowWindowPayload): Promise<void>;
+    listClients(): Promise<HubClientRecord[]>;
+    listSessions(limit?: number): Promise<SessionRecord[]>;
+    searchSessions(input: {
+        query: string;
+        limit?: number;
+        workspaceRoot?: string;
+    }): Promise<HubSessionSearchHit[]>;
+    toggleSetting(input: CoreSettingsToggleInput): Promise<CoreSettingsMutationResult>;
+    /**
+     * Subscribe to UI-relevant hub events.
+     * Returns an unsubscribe function.
+     */
+    subscribeUI(handlers: {
+        onNotify?: (payload: HubUINotifyPayload) => void;
+        onShowWindow?: (payload: HubUIShowWindowPayload) => void;
+        onClientRegistered?: (payload: Record<string, unknown>) => void;
+        onClientDisconnected?: (payload: Record<string, unknown>) => void;
+        onSessionCreated?: (payload: Record<string, unknown>) => void;
+        onSessionUpdated?: (payload: Record<string, unknown>) => void;
+        onSessionDetached?: (payload: Record<string, unknown>) => void;
+    }): () => void;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Resolves only after the daemon WebSocket server is listening and its process
+ * lifecycle handlers are installed.
+ */
+export declare const hubDaemonReady: Promise<void>;
+/**
+ * Abort-family rejections are expected daemon noise, not fatal faults: when a
+ * user cancels a turn, in-flight provider streams and fetches can reject on a
+ * floating promise after the run has already settled (DOMException
+ * "AbortError" from fetch/undici, Node ABORT_ERR, or the runtime's own
+ * AgentRuntimeAbortError). Exiting on those kills every resident session in
+ * the daemon — the next message from any connected client then lands on
+ * `session_not_found` and forces a rebuild from disk.
+ */
+export declare function isAbortRejection(reason: unknown): boolean;