@cline/core 0.0.92-nightly.1791773200 → 0.0.93

package/dist/extensions/plugin/plugin-registry.d.ts

@@ -0,0 +1,203 @@
+import type { AgentExtension, BasicLogger, PluginPolicies, PluginSetupContext, PluginStatusRecord, SessionPluginIssue } from "@cline/shared";
+import type { PluginInitializationFailure, PluginInitializationWarning } from "./plugin-load-report";
+import { type PluginTargeting } from "./plugin-targeting";
+export declare const DEFAULT_PLUGIN_IMPORT_TIMEOUT_MS = 4000;
+export declare const DEFAULT_PLUGIN_SETUP_TIMEOUT_MS = 4000;
+export declare const DEFAULT_PLUGIN_HOOK_TIMEOUT_MS = 3000;
+/** Tools, commands, rule content, and message builders. */
+export declare const DEFAULT_PLUGIN_TOOL_TIMEOUT_MS = 60000;
+/** Consecutive call failures after which a plugin is turned off. */
+export declare const DEFAULT_PLUGIN_FAILURE_THRESHOLD = 5;
+export type PluginHookErrorMode = "ignore" | "throw";
+export declare class PluginCallTimeoutError extends Error {
+    readonly label: string;
+    readonly timeoutMs: number;
+    constructor(label: string, timeoutMs: number);
+}
+export interface PluginRegistryOptions {
+    logger?: BasicLogger;
+    importTimeoutMs?: number;
+    setupTimeoutMs?: number;
+    hookTimeoutMs?: number;
+    toolTimeoutMs?: number;
+    failureThreshold?: number;
+}
+/**
+ * Where a session's plugin copies run. `in_process` imports them into the
+ * host. `worker` runs each plugin in its own worker thread per session: the
+ * host never loads plugin code, and a crash, `process.exit()`, or hung loop
+ * ends only that worker.
+ */
+export type PluginIsolation = "in_process" | "worker";
+export interface PluginSessionLoadInput extends PluginTargeting {
+    sessionId?: string;
+    /** Defaults to `in_process`. */
+    isolation?: PluginIsolation;
+    /** Resolved, enabled plugin module paths, in load order. */
+    pluginPaths: ReadonlyArray<string>;
+    /** Plugin paths turned off in settings; reported as `disabled`. */
+    disabledPluginPaths?: ReadonlyArray<string>;
+    /** Configured paths that could not be resolved to a module. */
+    discoveryFailures?: ReadonlyArray<{
+        pluginPath: string;
+        error: unknown;
+    }>;
+    policy?: PluginPolicies;
+    exportName?: string;
+    cwd?: string;
+    hookErrorMode?: PluginHookErrorMode;
+    setupContext?: PluginSetupContext;
+    emitEvent?: (event: {
+        name: string;
+        payload?: unknown;
+    }) => void;
+    /**
+     * Called when a call made for this session moves a plugin to `degraded`
+     * or `failed`. Setup runs lazily on the first turn, after the session
+     * start payload went out, so this is how those failures reach the user.
+     */
+    onIssue?: (issue: SessionPluginIssue) => void;
+    /** Per-session overrides of the registry's default timeouts. */
+    importTimeoutMs?: number;
+    hookTimeoutMs?: number;
+    /** Tools (without their own `timeoutMs`), commands, rules, builders. */
+    callTimeoutMs?: number;
+}
+export interface PluginSessionLoadResult {
+    extensions: AgentExtension[];
+    pluginPaths: string[];
+    failures: PluginInitializationFailure[];
+    warnings: PluginInitializationWarning[];
+    issues: SessionPluginIssue[];
+    /**
+     * Ends the session's use of its plugin copies: runs `ctx.onDispose`
+     * cleanup and stops further calls.
+     */
+    release: () => Promise<void>;
+}
+export type PluginStatusListener = (status: PluginStatusRecord) => void;
+/** The name a plugin is known by before its module is imported. */
+export declare function derivePluginNameFromPath(pluginPath: string): string;
+/**
+ * Plugins written for the subprocess sandbox emit events through
+ * `globalThis.__clinePluginHost.emitEvent`. In-process, route those calls to
+ * the session whose hook or tool is running (async context follows timers and
+ * promises the call started), else to the session that last called a plugin.
+ */
+export declare function installPluginHostShim(): void;
+/**
+ * Tracks plugins for the whole process and hands each session a guarded copy
+ * of the plugins it enabled. Each session gets its own import of the module,
+ * matching the per-session sandbox plugins were written for. Every import,
+ * setup, hook, tool, command, rule, and message-builder call is wrapped with
+ * a timeout and error capture, and the result is recorded per plugin so
+ * failures are visible instead of silently dropping the plugin's tools.
+ */
+export declare class PluginRegistry {
+    private readonly entries;
+    private readonly listeners;
+    private logger;
+    private readonly defaults;
+    private readonly failureThreshold;
+    constructor(options?: PluginRegistryOptions);
+    setLogger(logger: BasicLogger | undefined): void;
+    subscribe(listener: PluginStatusListener): () => void;
+    list(): PluginStatusRecord[];
+    get(nameOrPath: string): PluginStatusRecord[];
+    /**
+     * Re-imports the matching plugins and resets their status. Sessions
+     * started afterwards use the new module; running sessions keep the copy
+     * they set up, which stays callable unless the re-import fails (the plugin
+     * is then turned off for every session, failing closed).
+     */
+    reload(nameOrPath: string): Promise<PluginStatusRecord[]>;
+    /**
+     * Finds the plugin whose module root appears in `error`'s stack and turns
+     * it off for every session. Used by the Hub daemon so a stray plugin error
+     * does not take the process down.
+     */
+    attributeUncaughtError(error: unknown, label?: string): PluginStatusRecord | undefined;
+    /**
+     * Imports plugins without attaching them to a session, so the Hub can
+     * discover them at startup and report status before any session exists.
+     * The imported copy is kept for the first session to claim.
+     */
+    preload(input: Pick<PluginSessionLoadInput, "pluginPaths" | "disabledPluginPaths" | "discoveryFailures" | "exportName" | "importTimeoutMs" | "isolation">): Promise<PluginStatusRecord[]>;
+    loadForSession(input: PluginSessionLoadInput): Promise<PluginSessionLoadResult>;
+    /**
+     * Worker isolation: each plugin loads in its own worker for this session,
+     * and the copy handed to the session is a proxy whose calls go to that
+     * worker. The copy goes through the same wrapping as an in-process one, so
+     * status, timeouts, failure counting, policy, and notices are unchanged.
+     * What differs is where the code runs: the host never imports it.
+     */
+    private loadIsolatedForSession;
+    /**
+     * Every worker imports the module fresh, so new code needs no host
+     * re-import. A source change (or re-enabling) still starts a new import
+     * id: the plugin gets a clean slate, and copies of the old code go stale.
+     */
+    private refreshIsolatedEntry;
+    private startWorkerCopy;
+    /** Re-validates a worker plugin's current code in a throwaway worker. */
+    private reloadIsolated;
+    private staleIssue;
+    /**
+     * Records discovery failures and settings-disabled plugins. Settings-
+     * disabled plugins the session would otherwise use are reported as issues
+     * with `reason: "settings"`. Returns the entries that failed discovery.
+     */
+    private recordDiscovery;
+    private isEnabledForSession;
+    private policyIssue;
+    private resolveTimeouts;
+    private match;
+    private ensureEntry;
+    private ensureLoaded;
+    /** Imports one copy of the module in its own call scope. */
+    private importCopy;
+    /**
+     * Hands a session its own copy of the plugin module. Plugins written for
+     * the per-session sandbox keep state at module level (one plugin object
+     * per import), so sharing one copy across sessions would break them.
+     */
+    private claimInstance;
+    private importEntry;
+    private wrapForSession;
+    private runSetup;
+    private wrapHooks;
+    private wrapTool;
+    private wrapCommand;
+    /** A failing rule contributes no text rather than breaking the prompt. */
+    private wrapRule;
+    /** A failing builder leaves the message unchanged. */
+    private wrapMessageBuilder;
+    /**
+     * Runs one plugin call in its session scope with a timeout, records the
+     * outcome against the plugin, and rethrows failures.
+     */
+    private guardedCall;
+    /**
+     * Whether a session's copy may still be called: the plugin is not turned
+     * off, its setup did not fail, and its session has not ended.
+     */
+    private isUsable;
+    private assertUsable;
+    private releaseInstance;
+    private recordFailure;
+    private setState;
+    private warnIfSlow;
+    private log;
+    private toStatus;
+    private toIssue;
+    private toInitializationFailure;
+}
+/** One-line, user-facing description of a plugin a session cannot fully use. */
+export declare function formatSessionPluginIssue(issue: SessionPluginIssue): string;
+/**
+ * The registry shared by every session in this process. The Hub daemon reads
+ * it for `plugins.*` requests and to attribute stray plugin errors.
+ */
+export declare function getProcessPluginRegistry(): PluginRegistry;
+/** @internal Test hook. */
+export declare function resetProcessPluginRegistryForTests(registry?: PluginRegistry): void;

package/dist/extensions/plugin/plugin-sandbox.d.ts

@@ -2,10 +2,23 @@ import type { AgentConfig, PluginSetupContext, WorkspaceInfo } from "@cline/shar
 import type { PluginLoadDiagnostics } from "./plugin-load-report";
 import type { PluginTargeting } from "./plugin-targeting";
 export declare const CLINE_PLUGIN_IDLE_TIMEOUT_MS_ENV = "CLINE_PLUGIN_IDLE_TIMEOUT_MS";
+/**
+ * Absolute path to a compiled `plugin-sandbox-bootstrap.js`, for hosts that
+ * ship it somewhere this module cannot find on its own (an app bundle's
+ * resources directory).
+ */
+export declare const CLINE_PLUGIN_BOOTSTRAP_PATH_ENV = "CLINE_PLUGIN_BOOTSTRAP_PATH";
 export declare const DEFAULT_PLUGIN_SANDBOX_IDLE_TIMEOUT_MS: number;
 export type SandboxedPluginSetupContext = Pick<PluginSetupContext, "session" | "client" | "user" | "workspaceInfo" | "logger">;
+/**
+ * Where sandboxed plugins run. `subprocess` spawns a `node`/`bun` child and
+ * needs one on PATH; `worker` runs a worker thread inside the host runtime.
+ */
+export type PluginSandboxTransport = "subprocess" | "worker";
 export interface PluginSandboxOptions extends PluginTargeting {
     pluginPaths: string[];
+    /** Defaults to `subprocess`. */
+    transport?: PluginSandboxTransport;
     exportName?: string;
     /**
      * Max wall time for plugin module imports. Defaults to 4000 ms; falls back
@@ -26,6 +39,25 @@ export interface PluginSandboxOptions extends PluginTargeting {
         name: string;
         payload?: unknown;
     }) => void;
+    /** Worker transport only: the worker ended on its own (crash, exit). */
+    onUnexpectedExit?: (error: Error) => void;
+    /**
+     * Limit for each plugin's `setup()`, timed inside the sandbox and
+     * separately from the import. When set, the initialize call may take
+     * `importTimeoutMs + setupTimeoutMs`.
+     */
+    setupTimeoutMs?: number;
+    /** A plugin finished importing and its `setup()` is starting. */
+    onSetupStarted?: (pluginPath: string) => void;
+    /**
+     * Session plugin policy, applied inside the sandbox after each plugin is
+     * imported (when its own name is known) and before its `setup()` runs.
+     */
+    policy?: Record<string, {
+        enabled?: boolean;
+    } | undefined>;
+    /** Per plugin path: other names the policy may use (its file name). */
+    policyNames?: Record<string, string[]>;
     /**
      * The session's working directory. Forwarded to the sandbox subprocess so
      * that `process.cwd()` returns the correct path inside the sandbox even
@@ -75,8 +107,19 @@ export declare function selectBootstrapCandidate(options: {
 } | {
     sourcePath: string;
 };
+/**
+ * Whether this build can start the sandbox bootstrap: the compiled file ships
+ * beside it, or its TypeScript source exists (running from source). Bundles
+ * that ship neither cannot isolate plugins.
+ */
+export declare function isPluginSandboxBootstrapAvailable(): boolean;
 export declare function loadSandboxedPlugins(options: PluginSandboxOptions): Promise<{
     extensions: AgentConfig["extensions"];
     pluginPaths: string[];
+    /** Plugins the `policy` turned off; their setup did not run. */
+    disabledByPolicy: Array<{
+        pluginPath: string;
+        name: string;
+    }>;
     shutdown: () => Promise<void>;
 } & PluginLoadDiagnostics>;