@cline/core 0.0.38-nightly.1778113663

package/dist/auth/codex.d.ts

@@ -0,0 +1,43 @@
+/**
+ * OpenAI Codex (ChatGPT OAuth) flow
+ *
+ * NOTE: This module uses Node.js crypto and http for the OAuth callback.
+ * It is only intended for CLI use, not browser environments.
+ */
+import type { ITelemetryService } from "@cline/shared";
+import type { OAuthCredentials, OAuthPrompt, OAuthProviderInterface } from "./types";
+export declare const OPENAI_CODEX_OAUTH_CONFIG: {
+    readonly authorizationEndpoint: "https://auth.openai.com/oauth/authorize";
+    readonly tokenEndpoint: "https://auth.openai.com/oauth/token";
+    readonly clientId: "app_EMoamEEZ73f0CkXaXp7hrann";
+    readonly redirectUri: "http://localhost:1455/auth/callback";
+    readonly scopes: "openid profile email offline_access";
+    readonly callbackPort: 1455;
+    readonly jwtClaimPath: "https://api.openai.com/auth";
+    readonly refreshBufferMs: number;
+    readonly retryableTokenGraceMs: number;
+    readonly httpTimeoutMs: number;
+};
+export type RefreshTokenResolution = {
+    forceRefresh?: boolean;
+    refreshBufferMs?: number;
+    retryableTokenGraceMs?: number;
+};
+export declare function loginOpenAICodex(options: {
+    onAuth: (info: {
+        url: string;
+        instructions?: string;
+    }) => void;
+    onPrompt: (prompt: OAuthPrompt) => Promise<string>;
+    onProgress?: (message: string) => void;
+    onManualCodeInput?: () => Promise<string>;
+    originator?: string;
+    telemetry?: ITelemetryService;
+}): Promise<OAuthCredentials>;
+export declare function refreshOpenAICodexToken(refreshToken: string, fallback?: OAuthCredentials): Promise<OAuthCredentials>;
+export declare function getValidOpenAICodexCredentials(currentCredentials: OAuthCredentials | null, options?: RefreshTokenResolution & {
+    telemetry?: ITelemetryService;
+}): Promise<OAuthCredentials | null>;
+export declare function isOpenAICodexTokenExpired(credentials: OAuthCredentials, refreshBufferMs?: number): boolean;
+export declare function normalizeOpenAICodexCredentials(credentials: OAuthCredentials): OAuthCredentials;
+export declare const openaiCodexOAuthProvider: OAuthProviderInterface;

package/dist/auth/oca.d.ts

@@ -0,0 +1,28 @@
+import type { ITelemetryService } from "@cline/shared";
+import type { OAuthCredentials, OAuthLoginCallbacks, OAuthProviderInterface, OcaClientMetadata, OcaOAuthProviderOptions, OcaTokenResolution } from "./types";
+export declare const DEFAULT_INTERNAL_IDCS_CLIENT_ID = "a8331954c0cf48ba99b5dd223a14c6ea";
+export declare const DEFAULT_INTERNAL_IDCS_URL = "https://idcs-9dc693e80d9b469480d7afe00e743931.identity.oraclecloud.com";
+export declare const DEFAULT_INTERNAL_IDCS_SCOPES = "openid offline_access";
+export declare const DEFAULT_INTERNAL_OCA_BASE_URL = "https://code-internal.aiservice.us-chicago-1.oci.oraclecloud.com/20250206/app/litellm";
+export declare const DEFAULT_EXTERNAL_IDCS_CLIENT_ID = "c1aba3deed5740659981a752714eba33";
+export declare const DEFAULT_EXTERNAL_IDCS_URL = "https://login-ext.identity.oraclecloud.com";
+export declare const DEFAULT_EXTERNAL_IDCS_SCOPES = "openid offline_access";
+export declare const DEFAULT_EXTERNAL_OCA_BASE_URL = "https://code.aiservice.us-chicago-1.oci.oraclecloud.com/20250206/app/litellm";
+export declare const OCI_HEADER_OPC_REQUEST_ID = "opc-request-id";
+export declare function loginOcaOAuth(options: OcaOAuthProviderOptions & {
+    callbacks: OAuthLoginCallbacks;
+    telemetry?: ITelemetryService;
+}): Promise<OAuthCredentials>;
+export declare function refreshOcaToken(credentials: OAuthCredentials, options?: OcaOAuthProviderOptions): Promise<OAuthCredentials>;
+export declare function getValidOcaCredentials(currentCredentials: OAuthCredentials | null, options?: OcaTokenResolution & {
+    telemetry?: ITelemetryService;
+}, providerOptions?: OcaOAuthProviderOptions & {
+    telemetry?: ITelemetryService;
+}): Promise<OAuthCredentials | null>;
+export declare function createOcaOAuthProvider(options?: OcaOAuthProviderOptions): OAuthProviderInterface;
+export declare function generateOcaOpcRequestId(taskId: string, token: string): Promise<string>;
+export declare function createOcaRequestHeaders(input: {
+    accessToken: string;
+    taskId: string;
+    metadata?: OcaClientMetadata;
+}): Promise<Record<string, string>>;

package/dist/auth/server.d.ts

@@ -0,0 +1,54 @@
+export interface OAuthCallbackPayload {
+    url: URL;
+    code?: string;
+    state?: string;
+    provider?: string;
+    error?: string;
+}
+export interface OAuthServerListeningInfo {
+    host: string;
+    port: number;
+    callbackUrl: string;
+}
+export interface OAuthServerCloseInfo {
+    host: string;
+    port: number;
+}
+export interface LocalOAuthServerOptions {
+    host?: string;
+    ports: number[];
+    callbackPath: string;
+    timeoutMs?: number;
+    expectedState?: string;
+    successHtml?: string;
+    /**
+     * Called when the local redirect server successfully binds to a port and is
+     * ready to receive the OAuth callback. Hosts can use this to display a
+     * "waiting for callback" status indicator or — in remote-development
+     * environments like JetBrains Gateway — to forward the port from the remote
+     * machine to the local machine where the user's browser is running.
+     *
+     * May be async; `startLocalOAuthServer` will **await** this callback before
+     * returning so that any setup it performs (e.g. port-forwarding) is
+     * guaranteed to complete before the caller opens the auth URL. Errors
+     * thrown by this callback are swallowed — they do not prevent the OAuth
+     * flow from proceeding.
+     */
+    onListening?: (info: OAuthServerListeningInfo) => void | Promise<void>;
+    /**
+     * Called when the local redirect server closes, either because the OAuth
+     * callback was received, the flow was cancelled, or the timeout elapsed.
+     * Hosts should use this to tear down any port-forward set up in
+     * `onListening` and clear any "waiting for callback" status UI.
+     *
+     * May be async; fired after the underlying server socket is closed.
+     */
+    onClose?: (info: OAuthServerCloseInfo) => void | Promise<void>;
+}
+export interface LocalOAuthServer {
+    callbackUrl: string;
+    waitForCallback: () => Promise<OAuthCallbackPayload | null>;
+    cancelWait: () => void;
+    close: () => void;
+}
+export declare function startLocalOAuthServer(options: LocalOAuthServerOptions): Promise<LocalOAuthServer>;

package/dist/auth/types.d.ts

@@ -0,0 +1,103 @@
+import type { ITelemetryService } from "@cline/shared";
+import type { OAuthServerCloseInfo, OAuthServerListeningInfo } from "./server";
+export interface OAuthPrompt {
+    message: string;
+    defaultValue?: string;
+}
+export interface OAuthCredentials {
+    access: string;
+    refresh: string;
+    /**
+     * Expiration timestamp in milliseconds since epoch.
+     */
+    expires: number;
+    /**
+     * Optional provider-specific account identifier.
+     */
+    accountId?: string;
+    /**
+     * Optional email for display/telemetry.
+     */
+    email?: string;
+    /**
+     * Provider-specific metadata (user info, provider hint, etc).
+     */
+    metadata?: Record<string, unknown>;
+}
+export interface OAuthLoginCallbacks {
+    onAuth: (info: {
+        url: string;
+        instructions?: string;
+    }) => void;
+    onPrompt: (prompt: OAuthPrompt) => Promise<string>;
+    onProgress?: (message: string) => void;
+    onManualCodeInput?: () => Promise<string>;
+    /**
+     * Called when the local OAuth redirect server successfully binds to a port
+     * and is ready to receive the browser callback. The `info` object contains
+     * the host, the bound port number, and the full `callbackUrl`.
+     *
+     * Use this to:
+     * - Show a "waiting for OAuth callback on port N" status indicator in your UI.
+     * - Forward the port in remote-development environments (e.g. JetBrains
+     *   Gateway) from the remote machine to the machine running the browser.
+     *
+     * Paired with `onServerClose` for teardown.
+     *
+     * Only fired when the provider uses a local callback server
+     * (`OAuthProviderInterface.usesCallbackServer === true`).
+     */
+    onServerListening?: (info: OAuthServerListeningInfo) => void | Promise<void>;
+    /**
+     * Called when the local OAuth redirect server closes — either because the
+     * callback was received, the flow was cancelled, or the timeout elapsed.
+     *
+     * Use this to:
+     * - Clear any "waiting for callback" status UI shown in `onServerListening`.
+     * - Tear down port-forwards set up in `onServerListening`.
+     *
+     * Only fired when the provider uses a local callback server
+     * (`OAuthProviderInterface.usesCallbackServer === true`).
+     */
+    onServerClose?: (info: OAuthServerCloseInfo) => void | Promise<void>;
+}
+export interface OAuthProviderInterface {
+    id: string;
+    name: string;
+    usesCallbackServer: boolean;
+    login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+    refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+    getApiKey(credentials: OAuthCredentials): string;
+}
+export type OcaMode = "internal" | "external";
+export interface OcaOAuthEnvironmentConfig {
+    clientId: string;
+    idcsUrl: string;
+    scopes: string;
+    baseUrl: string;
+}
+export interface OcaOAuthConfig {
+    internal: OcaOAuthEnvironmentConfig;
+    external: OcaOAuthEnvironmentConfig;
+}
+export interface OcaClientMetadata {
+    client?: string;
+    clientVersion?: string;
+    clientIde?: string;
+    clientIdeVersion?: string;
+}
+export interface OcaOAuthProviderOptions {
+    config?: Partial<OcaOAuthConfig>;
+    mode?: OcaMode | (() => OcaMode);
+    callbackPath?: string;
+    callbackPorts?: number[];
+    requestTimeoutMs?: number;
+    refreshBufferMs?: number;
+    retryableTokenGraceMs?: number;
+    telemetry?: ITelemetryService;
+}
+export interface OcaTokenResolution {
+    forceRefresh?: boolean;
+    refreshBufferMs?: number;
+    retryableTokenGraceMs?: number;
+}

package/dist/auth/utils.d.ts

@@ -0,0 +1,32 @@
+import type { OAuthCallbackPayload } from "./server";
+import type { OAuthCredentials } from "./types";
+export declare function getProofKey(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+export declare function normalizeBaseUrl(value: string): string;
+export declare function resolveUrl(baseUrl: string, path: string): string;
+export type ParsedAuthorizationInput = {
+    code?: string;
+    state?: string;
+    provider?: string;
+};
+export type ParseAuthorizationInputOptions = {
+    includeProvider?: boolean;
+    allowHashCodeState?: boolean;
+};
+export declare function parseAuthorizationInput(input: string, options?: ParseAuthorizationInputOptions): ParsedAuthorizationInput;
+export declare function decodeJwtPayload(token?: string): Record<string, unknown> | null;
+export declare function parseOAuthError(text: string): {
+    code?: string;
+    message?: string;
+};
+export declare function isCredentialLikelyExpired(credentials: Pick<OAuthCredentials, "expires">, refreshBufferMs: number): boolean;
+export declare function resolveAuthorizationCodeInput(input: {
+    waitForCallback: () => Promise<OAuthCallbackPayload | null>;
+    cancelWait: () => void;
+    onManualCodeInput?: () => Promise<string>;
+    parseOptions?: ParseAuthorizationInputOptions;
+}): Promise<ParsedAuthorizationInput & {
+    error?: string;
+}>;

package/dist/cline-core/automation.d.ts

@@ -0,0 +1,34 @@
+import type { AutomationEventEnvelope, BasicLogger, ExtensionContext, ITelemetryService } from "@cline/shared";
+import type { CronService } from "../cron/service/cron-service";
+import type { HubScheduleRuntimeHandlers } from "../cron/service/schedule-service";
+import type { RuntimeHost } from "../runtime/host/runtime-host";
+import type { ClineAutomationEventIngressResult, ClineAutomationEventLog, ClineAutomationListEventsOptions, ClineAutomationListRunsOptions, ClineAutomationListSpecsOptions, ClineAutomationRun, ClineAutomationSpec, ClineCoreAutomationApi, ClineCoreAutomationOptions } from "./types";
+export declare function normalizeAutomationOptions(options: ClineCoreAutomationOptions | boolean | undefined): ClineCoreAutomationOptions | undefined;
+export declare function normalizeAutomationCronScope(scope: ClineCoreAutomationOptions["cronScope"]): "global" | "workspace" | undefined;
+export declare class ClineCoreAutomationController implements ClineCoreAutomationApi {
+    private readonly getService;
+    constructor(getService: () => CronService);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    reconcileNow(): Promise<void>;
+    ingestEvent(event: AutomationEventEnvelope): ClineAutomationEventIngressResult;
+    listEvents(options?: ClineAutomationListEventsOptions): ClineAutomationEventLog[];
+    getEvent(eventId: string): ClineAutomationEventLog | undefined;
+    listSpecs(options?: ClineAutomationListSpecsOptions): ClineAutomationSpec[];
+    listRuns(options?: ClineAutomationListRunsOptions): ClineAutomationRun[];
+}
+export interface ClineCoreAutomationRuntimeHandlersInput {
+    host: RuntimeHost;
+    getExtensionContext(): ExtensionContext | undefined;
+}
+export declare function createClineCoreAutomationRuntimeHandlers(input: ClineCoreAutomationRuntimeHandlersInput): HubScheduleRuntimeHandlers;
+export interface ClineCoreAutomationExtensionContextInput {
+    automationService?: CronService;
+    automation: ClineCoreAutomationApi;
+    context?: ExtensionContext;
+    clientName?: string;
+    distinctId?: string;
+    logger?: BasicLogger;
+    telemetry?: ITelemetryService;
+}
+export declare function createClineCoreAutomationExtensionContext(input: ClineCoreAutomationExtensionContextInput): ExtensionContext | undefined;

package/dist/cline-core/runtime-services.d.ts

@@ -0,0 +1,5 @@
+import type { PendingPromptsRuntimeService, PendingPromptsServiceApi, RuntimeHost, SessionModelRuntimeService, SessionUsageRuntimeService } from "../runtime/host/runtime-host";
+import { type ClineCoreSettingsApi } from "../settings";
+export type RuntimeHostServiceExtensions = RuntimeHost & Partial<PendingPromptsRuntimeService & SessionUsageRuntimeService & SessionModelRuntimeService>;
+export declare function createClineCoreSettingsApi(host: RuntimeHost): ClineCoreSettingsApi;
+export declare function createClineCorePendingPromptsApi(host: RuntimeHost): PendingPromptsServiceApi;

package/dist/cline-core/start-input.d.ts

@@ -0,0 +1,10 @@
+import type { ExtensionContext } from "@cline/shared";
+import type { RuntimeCapabilities } from "../runtime/capabilities";
+import type { StartSessionInput } from "../runtime/host/runtime-host";
+import type { ClineCoreStartInput } from "./types";
+export declare function toClineCoreStartInput(input: StartSessionInput | ClineCoreStartInput): ClineCoreStartInput;
+export interface NormalizeClineCoreStartInputOptions {
+    defaultCapabilities?: RuntimeCapabilities;
+    withExtensionContext?: (context?: ExtensionContext) => ExtensionContext | undefined;
+}
+export declare function normalizeClineCoreStartInput(input: ClineCoreStartInput, options?: NormalizeClineCoreStartInputOptions): StartSessionInput;

package/dist/cline-core/telemetry.d.ts

@@ -0,0 +1,10 @@
+import type { ITelemetryService } from "@cline/shared";
+import type { ClineCoreStartInput } from "./types";
+export interface EmitSessionStartedTelemetryInput {
+    input: ClineCoreStartInput;
+    sessionId: string;
+    telemetry?: ITelemetryService;
+    clientName?: string;
+    runtimeAddress?: string;
+}
+export declare function emitSessionStartedTelemetry(input: EmitSessionStartedTelemetryInput): void;

package/dist/cline-core/types.d.ts

@@ -0,0 +1,221 @@
+import type { Message } from "@cline/llms";
+import type { AgentConfig, AutomationEventEnvelope, BasicLogger, ITelemetryService } from "@cline/shared";
+import type { CronEventSuppression } from "../cron/events/cron-event-ingress";
+import type { CronEventLogRecord, CronRunRecord, CronSpecRecord } from "../cron/store/sqlite-cron-store";
+import type { CheckpointEntry } from "../hooks/checkpoint-hooks";
+import type { RuntimeCapabilities } from "../runtime/capabilities";
+import type { SessionHistoryListOptions } from "../runtime/host/history";
+import type { SessionBackend } from "../runtime/host/host";
+import type { LocalRuntimeStartOptions, RuntimeHostMode, StartSessionInput, StartSessionResult } from "../runtime/host/runtime-host";
+import type { CoreSessionConfig } from "../types/config";
+import type { SessionMessagesArtifactUploader } from "../types/session";
+export type { RuntimeHostMode } from "../runtime/host/runtime-host";
+export type { ClineCoreSettingsApi } from "../settings";
+export interface HubOptions {
+    endpoint?: string;
+    authToken?: string;
+    strategy?: "prefer-hub" | "require-hub";
+    clientType?: string;
+    displayName?: string;
+    workspaceRoot?: string;
+    cwd?: string;
+}
+export interface RemoteOptions {
+    endpoint: string;
+    authToken?: string;
+    clientType?: string;
+    displayName?: string;
+    workspaceRoot?: string;
+    cwd?: string;
+}
+export interface ClineCoreAutomationOptions {
+    /** @deprecated Use `cronSpecsDir`. */
+    cronDir?: string;
+    cronSpecsDir?: string;
+    /** @deprecated Reports are written under the resolved cron specs directory. */
+    reportsDir?: string;
+    cronScope?: "global" | "user" | "workspace";
+    workspaceRoot?: string;
+    dbPath?: string;
+    pollIntervalMs?: number;
+    claimLeaseSeconds?: number;
+    globalMaxConcurrency?: number;
+    watcherDebounceMs?: number;
+    autoStart?: boolean;
+}
+export type ClineAutomationSpec = CronSpecRecord;
+export type ClineAutomationRun = CronRunRecord;
+export type ClineAutomationEventLog = CronEventLogRecord;
+export type ClineAutomationEventSuppression = CronEventSuppression;
+export type ClineAutomationRunStatus = "queued" | "running" | "done" | "failed" | "cancelled";
+export interface ClineAutomationListSpecsOptions {
+    triggerKind?: "one_off" | "schedule" | "event";
+    enabled?: boolean;
+    parseStatus?: "valid" | "invalid";
+    includeRemoved?: boolean;
+    limit?: number;
+}
+export interface ClineAutomationListRunsOptions {
+    specId?: string;
+    status?: ClineAutomationRunStatus | ClineAutomationRunStatus[];
+    limit?: number;
+}
+export interface ClineAutomationListEventsOptions {
+    eventType?: string;
+    source?: string;
+    processingStatus?: "received" | "unmatched" | "queued" | "suppressed" | "failed";
+    limit?: number;
+}
+export interface ClineAutomationEventIngressResult {
+    event: ClineAutomationEventLog;
+    duplicate: boolean;
+    matchedSpecIds: string[];
+    queuedRuns: ClineAutomationRun[];
+    suppressions: ClineAutomationEventSuppression[];
+}
+export interface ClineCoreAutomationApi {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    reconcileNow(): Promise<void>;
+    ingestEvent(event: AutomationEventEnvelope): ClineAutomationEventIngressResult;
+    listEvents(options?: ClineAutomationListEventsOptions): ClineAutomationEventLog[];
+    getEvent(eventId: string): ClineAutomationEventLog | undefined;
+    listSpecs(options?: ClineAutomationListSpecsOptions): ClineAutomationSpec[];
+    listRuns(options?: ClineAutomationListRunsOptions): ClineAutomationRun[];
+}
+export type ClineCoreListHistoryOptions = SessionHistoryListOptions;
+export interface ClineCoreStartInput extends Omit<StartSessionInput, "config" | "localRuntime"> {
+    config: CoreSessionConfig;
+    localRuntime?: LocalRuntimeStartOptions;
+}
+export interface RestoreOptions {
+    /**
+     * Restore the message history by starting a new session fork trimmed to
+     * `checkpointRunCount`. Defaults to true.
+     */
+    messages?: boolean;
+    /**
+     * Restore the workspace files from the checkpoint's git snapshot.
+     * Defaults to true.
+     */
+    workspace?: boolean;
+    /**
+     * Start the forked session with messages before the checkpoint user message
+     * while still returning messages through that user message. This is for
+     * clients that put the checkpoint message back into a compose box so it can
+     * be edited and submitted again without duplicating it in session history.
+     */
+    omitCheckpointMessageFromSession?: boolean;
+}
+export interface RestoreInput {
+    sessionId: string;
+    checkpointRunCount: number;
+    start?: ClineCoreStartInput;
+    cwd?: string;
+    restore?: RestoreOptions;
+}
+export interface RestoreResult {
+    sessionId?: string;
+    startResult?: StartSessionResult;
+    messages?: Message[];
+    checkpoint: CheckpointEntry;
+}
+export interface ClineCoreOptions {
+    /**
+     * A human-readable name for this SDK client (e.g. `"my-app"`, `"acme-bot"`).
+     * Used to identify the consumer in telemetry and logs.
+     */
+    clientName?: string;
+    /**
+     * A stable identifier for this machine or user, used for telemetry attribution.
+     * Defaults to the system machine ID, falling back to a generated `cl-<nanoid>` persisted
+     * at `~/.cline/data/machine-id`.
+     */
+    distinctId?: string;
+    /**
+     * Controls how the runtime host is selected:
+     * - `"auto"` (default) — prefers a compatible local hub when one is available and falls
+     *   back to local in-process execution when not.
+     * - `"hub"` — requires a compatible websocket hub runtime; throws if one is not reachable.
+     * - `"remote"` — requires an explicit remote websocket hub endpoint.
+     * - `"local"` — always uses local in-process execution and local SQLite/file storage.
+     */
+    backendMode?: RuntimeHostMode;
+    /**
+     * Hub runtime connection options. Used when `backendMode` is `"hub"` or when `"auto"`
+     * should prefer a shared local hub if available.
+     */
+    hub?: HubOptions;
+    /**
+     * Remote hub connection options. Only relevant when `backendMode` is `"remote"`.
+     */
+    remote?: RemoteOptions;
+    /**
+     * Client-owned runtime capabilities. Core adapts these handlers to the
+     * selected runtime backend so apps implement interactive behavior once.
+     */
+    capabilities?: RuntimeCapabilities;
+    /**
+     * Telemetry service instance to use for capturing events and usage.
+     * If omitted, telemetry is a no-op.
+     */
+    telemetry?: ITelemetryService;
+    /**
+     * Optional structured logger for core-side operational diagnostics such as
+     * runtime-host selection and fallback decisions.
+     */
+    logger?: BasicLogger;
+    /**
+     * Per-tool approval policies that control whether a tool runs automatically,
+     * requires user confirmation, or is blocked entirely.
+     */
+    toolPolicies?: AgentConfig["toolPolicies"];
+    /**
+     * Optional hook invoked after `messages.json` is persisted to disk.
+     * Consumers can use this to mirror session transcripts into remote storage.
+     */
+    messagesArtifactUploader?: SessionMessagesArtifactUploader;
+    /**
+     * Enables file-based and event-driven automation through this ClineCore
+     * instance. When configured, callers use `cline.automation.*` instead of
+     * constructing cron services directly.
+     */
+    automation?: boolean | ClineCoreAutomationOptions;
+    /**
+     * Custom `fetch` implementation forwarded to the AI gateway providers used
+     * by local sessions. When supplied, it is threaded into each
+     * `ProviderConfig.fetch` built during session bootstrap, which in turn
+     * populates `GatewayProviderSettings.fetch` (and the top-level
+     * `GatewayConfig.fetch` fallback) so hosts can inject custom HTTP behavior
+     * such as proxies, retries, tracing, or test doubles.
+     *
+     * Per-session or per-provider overrides still win: an explicit
+     * `config.fetch` on `CoreSessionConfig` or a stored provider-level `fetch`
+     * takes precedence over this default.
+     *
+     * Applies only to sessions executed in this process (local and fallback-
+     * to-local auto mode). For hub and remote runtimes the HTTP call happens
+     * inside the process that owns the gateway, so configure `fetch` there:
+     *   - `startHubServer({ fetch })` / `ensureHubServer({ fetch })` from
+     *     `@cline/hub`
+     *   - `createLocalHubScheduleRuntimeHandlers({ fetch })` from
+     *     `@cline/core/hub` for the scheduler
+     */
+    fetch?: typeof fetch;
+    /**
+     * An already-constructed session backend to use instead of resolving one automatically.
+     * Intended for testing or embedding a custom persistence layer.
+     * @internal
+     */
+    sessionService?: SessionBackend;
+    /**
+     * Optional hook invoked before each session starts.
+     * Use this to prepare workspace-scoped runtime state and then return an
+     * adapter that mutates the shared session input before core starts the run.
+     */
+    prepare?: (input: ClineCoreStartInput) => Promise<StartSessionBootstrap | undefined> | StartSessionBootstrap | undefined;
+}
+export interface StartSessionBootstrap {
+    applyToStartSessionInput(input: ClineCoreStartInput): Promise<ClineCoreStartInput> | ClineCoreStartInput;
+    dispose?(): Promise<void> | void;
+}

package/dist/cron/events/cron-event-ingress.d.ts

@@ -0,0 +1,37 @@
+import type { AutomationEventEnvelope, BasicLogger } from "@cline/shared";
+import type { CronEventLogRecord, CronRunRecord, CronSpecRecord, SqliteCronStore } from "../store/sqlite-cron-store";
+/**
+ * Durable ingress for normalized automation events.
+ *
+ * This layer persists the incoming event before matching, then materializes
+ * queued `cron_runs` for matching event specs. It deliberately does not
+ * execute agents; the normal runner claim loop owns execution.
+ */
+export interface CronEventIngressOptions {
+    store: SqliteCronStore;
+    now?: () => number;
+    logger?: BasicLogger;
+}
+export type CronEventSuppressionReason = "duplicate_event" | "filter_mismatch" | "dedupe_window" | "cooldown";
+export interface CronEventSuppression {
+    specId?: string;
+    externalId?: string;
+    reason: CronEventSuppressionReason;
+    dedupeKey?: string;
+}
+export interface CronEventIngressResult {
+    event: CronEventLogRecord;
+    duplicate: boolean;
+    matchedSpecs: CronSpecRecord[];
+    queuedRuns: CronRunRecord[];
+    suppressions: CronEventSuppression[];
+}
+export declare function automationEventMatchesFilters(event: AutomationEventEnvelope, filters: Record<string, unknown> | undefined): boolean;
+export declare class CronEventIngress {
+    private readonly store;
+    private readonly nowFn;
+    private readonly logger?;
+    constructor(options: CronEventIngressOptions);
+    ingestEvent(event: AutomationEventEnvelope): CronEventIngressResult;
+    private materializeForSpec;
+}

package/dist/cron/reports/cron-report-writer.d.ts

@@ -0,0 +1,40 @@
+import { type ResolveCronSpecsDirOptions } from "@cline/shared/storage";
+import type { CronEventLogRecord, CronRunRecord, CronSpecRecord } from "../store/sqlite-cron-store";
+/**
+ * Writes a markdown report for a completed or failed cron run.
+ * Reports live under `<cron-specs-dir>/reports/<run-id>.md`.
+ * By default that is `~/.cline/cron/reports/<run-id>.md`.
+ * and are derived artifacts — the database is still the operational source
+ * of truth.
+ */
+export interface CronRunReportData {
+    finalText?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+        totalCost?: number;
+    };
+    toolCalls?: Array<{
+        name: string;
+        error?: string;
+        durationMs?: number;
+    }>;
+    durationMs?: number;
+    error?: string;
+    triggerEvent?: CronEventLogRecord;
+}
+export interface WriteReportOptions {
+    /**
+     * Cron spec source/report location. Defaults to global `~/.cline/cron`.
+     * Pass `{ scope: "workspace", workspaceRoot }` to write reports beside a
+     * future workspace-scoped cron specs directory.
+     */
+    specs?: ResolveCronSpecsDirOptions;
+    workspaceRoot: string;
+    run: CronRunRecord;
+    spec: CronSpecRecord;
+    data: CronRunReportData;
+}
+export declare function writeCronRunReport(options: WriteReportOptions): string;

package/dist/cron/runner/cron-materializer.d.ts

@@ -0,0 +1,35 @@
+import type { CronSpecRecord, SqliteCronStore } from "../store/sqlite-cron-store";
+/**
+ * Queue materialization rules shared between the reconciler, watcher, and
+ * periodic runner tick. Execution stays trigger-agnostic once a row is
+ * queued; this module is the only place that decides when to create a row.
+ */
+export interface CronMaterializerOptions {
+    store: SqliteCronStore;
+    now?: () => number;
+}
+export interface MaterializeSummary {
+    oneOffQueued: number;
+    scheduleQueued: number;
+}
+export declare class CronMaterializer {
+    private readonly store;
+    private readonly nowFn;
+    constructor(options: CronMaterializerOptions);
+    /**
+     * Run materialization for every valid/enabled spec. Typically called at
+     * startup (after reconciliation) and on each runner tick.
+     */
+    materializeAll(): MaterializeSummary;
+    /**
+     * Ensure a single one-off spec has exactly one run record for its current
+     * revision unless an explicit rerun path creates a different trigger kind.
+     * Returns true if a new queued run was created.
+     */
+    materializeOneOff(spec: CronSpecRecord): boolean;
+    /**
+     * Materialize schedule runs. Implements the "one overdue catch-up on
+     * startup, then advance" policy described in PLAN.md.
+     */
+    materializeSchedule(spec: CronSpecRecord): boolean;
+}