@cline/core 0.0.92 → 0.0.93-nightly.1792117748

package/dist/cron/store/sqlite-cron-store.d.ts

@@ -244,6 +244,12 @@ export declare class SqliteCronStore {
     hasConsumedOneOffRevision(specId: string, revision: number): boolean;
     enqueueRun(input: EnqueueRunInput): CronRunRecord;
     cancelQueuedRunsForSpec(specId: string): number;
+    /**
+     * Cancels queued cron occurrences superseded by a newer queued occurrence
+     * of the same spec, so a backlog runs once instead of replaying every
+     * missed slot back to back.
+     */
+    cancelSupersededScheduleRuns(): number;
     private cancelQueuedOneOffRunsForSpec;
     claimDueRuns(options: ClaimRunOptions): ClaimedCronRun[];
     renewClaim(runId: string, claimToken: string, leaseUntilAt: string): boolean;

package/dist/extensions/composio/composio-meta-tools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * In-chat authentication for Composio connectors.
+ *
+ * The Cline API creates a per-user Composio tool-router session scoped to the
+ * project's enabled auth configs (`POST /api/v1/connectors/meta-tools/sessions`)
+ * and returns the schemas of its allowlisted meta tools: COMPOSIO_SEARCH_TOOLS
+ * finds tools across those toolkits, COMPOSIO_MANAGE_CONNECTIONS returns a
+ * hosted Connect Link the agent surfaces in chat, COMPOSIO_WAIT_FOR_CONNECTIONS
+ * blocks until the user finishes, and COMPOSIO_MULTI_EXECUTE_TOOL runs the
+ * tools search found — no new session needed after connecting.
+ * Credentials never pass through Cline or the model — only the link does.
+ * Executions go back through the proxy with the session id
+ * (`POST /api/v1/connectors/meta-tools/{slug}/execute`), which checks that the
+ * session belongs to the caller.
+ */
+export declare const CONNECTORS_API_PATH = "/api/v1/connectors";
+/** The host owns the API origin and user authentication for connector requests. */
+export type ConnectorsRequest = (path: string, init: RequestInit) => Promise<Response>;
+export type ComposioMetaTool = {
+    slug: string;
+    name?: string;
+    description?: string;
+    input_parameters?: Record<string, unknown>;
+};
+export type ComposioMetaToolSession = {
+    sessionId: string;
+    tools: ComposioMetaTool[];
+};
+/**
+ * Creates a meta-tool session, or returns undefined when in-chat auth is
+ * unavailable: no connectable toolkits (404), a proxy without the endpoint, or
+ * any network failure. Callers then run without the meta tools.
+ */
+export declare function createComposioMetaToolSession(request: ConnectorsRequest, options?: {
+    log?: (message: string) => void;
+}): Promise<ComposioMetaToolSession | undefined>;
+export declare function executeComposioMetaTool(request: ConnectorsRequest, sessionId: string, slug: string, input: unknown): Promise<unknown>;

package/dist/extensions/composio/composio-tools-extension.d.ts

@@ -1,13 +1,8 @@
 import type { AgentExtension, BasicLogger } from "@cline/shared";
-export declare function resolveComposioToolsStatePath(accountId: string): string;
-/**
- * Builds the extension for the current connector state, or undefined when
- * there is nothing to register (no state file, or no connected toolkit with
- * tools) — sessions without connectors pay one file read.
- *
- * The state is read once here, at session-bootstrap time, so a session's
- * tool set is frozen at start exactly like the previous plugin's was.
- */
+import { type ConnectorsRequest } from "./composio-meta-tools";
+export declare function resolveComposioConnectionStatePath(accountId: string): string;
+/** Builds the meta-tool extension independently of saved connections. */
 export declare function createComposioToolsExtension(options?: {
+    request?: ConnectorsRequest;
     logger?: BasicLogger;
 }): Promise<AgentExtension | undefined>;

package/dist/extensions/index.d.ts

@@ -1,7 +1,10 @@
 export type { AgentPluginPackageDiagnostic, AgentPluginPackageDiagnosticScope, AgentPluginPackageLoadReport, AgentPluginPackageManifest, AgentPluginPackageMcpServer, AgentPluginPackageSkill, AgentSkillMetadata, LoadAgentPluginPackagesOptions, LoadedAgentPluginPackage, ParsedAgentSkill, } from "./agent-plugin";
 export { AGENT_PLUGINS_V1_MANIFEST_SCHEMA, AGENT_PLUGINS_V1_MCP_SCHEMA, loadAgentPluginPackages, parseAgentSkillMarkdown, } from "./agent-plugin";
-export type { ResolveAgentPluginPathsOptions } from "./plugin/plugin-config-loader";
-export { discoverPluginModulePaths, getPluginDisplayName, resolveAgentPluginPaths, resolveAndLoadAgentPlugins, resolvePluginConfigSearchPaths, resolvePluginSkillDirectoriesFromPaths, } from "./plugin/plugin-config-loader";
+export type { PluginExecutionMode, ResolveAgentPluginPathsOptions, } from "./plugin/plugin-config-loader";
+export { CLINE_PLUGIN_MODE_ENV, discoverPluginModulePaths, getPluginDisplayName, resolveAgentPluginPaths, resolveAgentPluginPathsWithDiagnostics, resolveAndLoadAgentPlugins, resolvePluginConfigSearchPaths, resolvePluginExecutionMode, resolvePluginSkillDirectoriesFromPaths, } from "./plugin/plugin-config-loader";
 export type { PluginInitializationFailure, PluginInitializationWarning, PluginLoadDiagnostics, } from "./plugin/plugin-load-report";
 export type { LoadAgentPluginFromPathOptions } from "./plugin/plugin-loader";
 export { loadAgentPluginFromPath, loadAgentPluginsFromPaths, loadAgentPluginsFromPathsWithDiagnostics, } from "./plugin/plugin-loader";
+export type { PluginHookErrorMode, PluginRegistryOptions, PluginSessionLoadInput, PluginSessionLoadResult, PluginStatusListener, } from "./plugin/plugin-registry";
+export { DEFAULT_PLUGIN_FAILURE_THRESHOLD, DEFAULT_PLUGIN_HOOK_TIMEOUT_MS, DEFAULT_PLUGIN_IMPORT_TIMEOUT_MS, DEFAULT_PLUGIN_SETUP_TIMEOUT_MS, DEFAULT_PLUGIN_TOOL_TIMEOUT_MS, formatSessionPluginIssue, getProcessPluginRegistry, PluginCallTimeoutError, PluginRegistry, } from "./plugin/plugin-registry";
+export { CLINE_PLUGIN_BOOTSTRAP_PATH_ENV } from "./plugin/plugin-sandbox";

package/dist/extensions/plugin/plugin-config-loader.d.ts

@@ -1,7 +1,9 @@
-import type { AgentConfig, PluginSetupContext, WorkspaceInfo } from "@cline/shared";
+import type { AgentConfig, PluginPolicies, PluginSetupContext, SessionPluginIssue, WorkspaceInfo } from "@cline/shared";
+import { getPluginDisplayName } from "@cline/shared/storage";
 import type { PluginLoadDiagnostics } from "./plugin-load-report";
+import { type PluginHookErrorMode, type PluginRegistry } from "./plugin-registry";
 import type { PluginTargeting } from "./plugin-targeting";
-export { getPluginDisplayName } from "@cline/shared/storage";
+export { getPluginDisplayName };
 type AgentPlugin = NonNullable<AgentConfig["extensions"]>[number];
 export declare function resolvePluginConfigSearchPaths(workspacePath?: string): string[];
 export declare function discoverPluginModulePaths(directoryPath: string): string[];
@@ -11,11 +13,38 @@ export interface ResolveAgentPluginPathsOptions {
     cwd?: string;
     includeDisabled?: boolean;
 }
+/**
+ * Like {@link resolveAgentPluginPaths}, but never throws: configured paths
+ * that cannot be resolved come back as `discoveryFailures`, and paths turned
+ * off in settings come back as `disabledPaths`, so callers can report both.
+ */
+export declare function resolveAgentPluginPathsWithDiagnostics(options?: ResolveAgentPluginPathsOptions): {
+    paths: string[];
+    disabledPaths: string[];
+    discoveryFailures: Array<{
+        pluginPath: string;
+        error: unknown;
+    }>;
+};
 export declare function resolveAgentPluginPaths(options?: ResolveAgentPluginPathsOptions): string[];
 export declare function resolvePluginSkillDirectoriesFromPaths(pluginPaths: ReadonlyArray<string>): string[];
 export declare function resolveAgentPluginSkillDirectories(options?: ResolveAgentPluginPathsOptions): string[];
+export type PluginExecutionMode = "sandbox" | "worker";
+export declare const CLINE_PLUGIN_MODE_ENV = "CLINE_PLUGIN_MODE";
+/**
+ * Where plugins run (`CLINE_PLUGIN_MODE`, or `mode`):
+ * - `worker` (default): each plugin runs in its own worker thread per
+ *   session, inside the host runtime. A plugin crash, `process.exit()`, or
+ *   hung loop ends only its worker, and no `node`/`bun` is needed on PATH.
+ * - `sandbox`: the previous per-session `node`/`bun` subprocess.
+ *
+ * Plugin code never runs on a host's main thread. Both modes need the
+ * sandbox bootstrap; a build that ships none fails every plugin load with
+ * `PluginBootstrapMissingError` rather than importing plugins into the host.
+ */
+export declare function resolvePluginExecutionMode(mode?: PluginExecutionMode): PluginExecutionMode;
 export interface ResolveAndLoadAgentPluginsOptions extends ResolveAgentPluginPathsOptions, PluginTargeting {
-    mode?: "sandbox" | "in_process";
+    mode?: PluginExecutionMode;
     exportName?: string;
     importTimeoutMs?: number;
     hookTimeoutMs?: number;
@@ -25,9 +54,8 @@ export interface ResolveAndLoadAgentPluginsOptions extends ResolveAgentPluginPat
         payload?: unknown;
     }) => void;
     /**
-     * Structured workspace and git metadata. Forwarded to sandboxed plugins
-     * via PluginSetupCtx.workspaceInfo and made available to in-process plugins
-     * in the extension context.
+     * Structured workspace and git metadata, forwarded to plugins via
+     * PluginSetupCtx.workspaceInfo.
      */
     workspaceInfo?: WorkspaceInfo;
     session?: PluginSetupContext["session"];
@@ -36,9 +64,22 @@ export interface ResolveAndLoadAgentPluginsOptions extends ResolveAgentPluginPat
     automation?: PluginSetupContext["automation"];
     logger?: PluginSetupContext["logger"];
     telemetry?: PluginSetupContext["telemetry"];
+    /**
+     * Per-session plugin selection (`"*"` default plus per-plugin overrides).
+     * Worker mode only; the subprocess sandbox loads every discovered plugin.
+     */
+    policy?: PluginPolicies;
+    /** How a failing plugin hook affects the run. Defaults to `"ignore"`. */
+    hookErrorMode?: PluginHookErrorMode;
+    /** Worker mode: the registry to load through. Defaults to the process-wide one. */
+    registry?: PluginRegistry;
+    /** Worker mode only: a plugin this session uses became degraded or failed. */
+    onIssue?: (issue: SessionPluginIssue) => void;
 }
 export declare function resolveAndLoadAgentPlugins(options?: ResolveAndLoadAgentPluginsOptions): Promise<{
     extensions: AgentPlugin[];
     pluginPaths: string[];
+    /** Plugins the session asked for but does not have (failed, disabled). */
+    issues: SessionPluginIssue[];
     shutdown?: () => Promise<void>;
 } & PluginLoadDiagnostics>;

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

@@ -0,0 +1,43 @@
+import type { AgentExtension, AgentExtensionCommand, AgentExtensionMcpServer, AgentExtensionProvider, AgentExtensionRule, AgentTool, PluginStatusRecord } from "@cline/shared";
+import { type PluginExecutionMode } from "./plugin-config-loader";
+import type { PluginInitializationFailure, PluginInitializationWarning } from "./plugin-load-report";
+import { type PluginRegistry } from "./plugin-registry";
+import type { PluginTargeting } from "./plugin-targeting";
+export interface CollectedPluginContributions {
+    pluginName: string;
+    pluginPath: string;
+    extension: AgentExtension;
+    tools: AgentTool[];
+    rules: AgentExtensionRule[];
+    commands: AgentExtensionCommand[];
+    mcpServers: AgentExtensionMcpServer[];
+    providers: AgentExtensionProvider[];
+}
+export interface CollectPluginContributionsInput extends PluginTargeting {
+    pluginPaths: ReadonlyArray<string>;
+    disabledPluginPaths?: ReadonlyArray<string>;
+    discoveryFailures?: ReadonlyArray<{
+        pluginPath: string;
+        error: unknown;
+    }>;
+    cwd?: string;
+    workspacePath?: string;
+    registry?: PluginRegistry;
+    /** Defaults to the configured execution mode (`CLINE_PLUGIN_MODE`). */
+    mode?: PluginExecutionMode;
+}
+export interface CollectPluginContributionsResult {
+    plugins: CollectedPluginContributions[];
+    /** Status of every plugin that failed to import or set up. */
+    failed: PluginStatusRecord[];
+    failures: PluginInitializationFailure[];
+    warnings: PluginInitializationWarning[];
+}
+/**
+ * Runs each plugin's `setup` with a collecting API, for settings surfaces
+ * that list what plugins contribute without starting a session. Plugins load
+ * the same way sessions load them: through the shared registry's workers, so
+ * failures are recorded there like any other, or through the subprocess
+ * sandbox when `CLINE_PLUGIN_MODE=sandbox`.
+ */
+export declare function collectPluginContributions(input: CollectPluginContributionsInput): Promise<CollectPluginContributionsResult>;

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

@@ -5,6 +5,8 @@ export interface LoadAgentPluginFromPathOptions {
     exportName?: string;
     cwd?: string;
     useCache?: boolean;
+    /** Fresh module evaluation that still reuses the transform cache. */
+    freshModule?: boolean;
     session?: PluginSetupContext["session"];
     client?: PluginSetupContext["client"];
     user?: PluginSetupContext["user"];

package/dist/extensions/plugin/plugin-module-import.d.ts

@@ -1,4 +1,17 @@
 export interface ImportPluginModuleOptions {
     useCache?: boolean;
+    /**
+     * Evaluate the module again (no module cache) but reuse jiti's on-disk
+     * transform cache, so a fresh per-session copy skips the babel transform.
+     */
+    freshModule?: boolean;
 }
+/**
+ * Content fingerprint of a plugin's own source: the entry file plus every
+ * file it reaches through relative static imports (`node_modules` and other
+ * bare imports are not included). Used to tell whether a plugin changed since
+ * it was last imported, including edits outside the entry file and edits that
+ * keep the same size within one clock tick.
+ */
+export declare function fingerprintPluginSources(pluginPath: string): string;
 export declare function importPluginModule(pluginPath: string, options?: ImportPluginModuleOptions): Promise<Record<string, unknown>>;

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

@@ -0,0 +1,172 @@
+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;
+}
+export interface PluginSessionLoadInput extends PluginTargeting {
+    sessionId?: string;
+    /** 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;
+/**
+ * Tracks plugins for the whole process and hands each session a guarded copy
+ * of the plugins it enabled. Each copy runs in its own worker thread, so
+ * module state is per session and plugin code never runs on the host's main
+ * thread. 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-validates the matching plugins' current code in throwaway workers and
+     * resets their status. Sessions started afterwards use the new code;
+     * 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[]>;
+    /**
+     * Loads each plugin in a throwaway worker without attaching it to a
+     * session, so the Hub can discover plugins at startup and report status
+     * (including import errors) before any session exists.
+     */
+    preload(input: Pick<PluginSessionLoadInput, "pluginPaths" | "disabledPluginPaths" | "discoveryFailures" | "exportName" | "importTimeoutMs">): Promise<PluginStatusRecord[]>;
+    /**
+     * 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 host
+     * never imports plugin code. Every setup, hook, tool, command, rule, and
+     * message-builder call is wrapped with a timeout and error capture, and
+     * the result is recorded per plugin.
+     */
+    loadForSession(input: PluginSessionLoadInput): Promise<PluginSessionLoadResult>;
+    /**
+     * 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 refreshEntry;
+    private startWorkerCopy;
+    /** Re-validates a plugin's current code in a throwaway worker. */
+    private reloadEntry;
+    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 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 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
@@ -74,9 +106,23 @@ export declare function selectBootstrapCandidate(options: {
     file: string;
 } | {
     sourcePath: string;
-};
+} | undefined;
+/**
+ * @internal Test hook: behave as a host that ships no bootstrap. Tests run
+ * from source, where the `.ts` bootstrap always resolves.
+ */
+export declare function setPluginBootstrapUnavailableForTests(unavailable: boolean): void;
+/** This build ships no `plugin-sandbox-bootstrap.js`, so no plugin can run. */
+export declare class PluginBootstrapMissingError extends Error {
+    constructor();
+}
 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>;