@dsh-plugin/dsh-loader 1.1.0-dev.32287576957 → 1.2.0

package/lib/types/adapters/dsh-1-x.d.ts

@@ -0,0 +1,23 @@
+import type { CordisContext, HostAdapterConfig } from '../types.js';
+export declare const supports = ">=0.1.0-rc.1 <2.0.0";
+export declare const name = "dsh-1-x";
+export declare const BRIDGE_PREFIX = "/api/dshloader";
+export declare const hostPackageAliases: Record<string, string>;
+/**
+ * Install a Module._resolveFilename hook that maps old package names to
+ * new ones for CJS require() calls. Returns a dispose function that
+ * removes the hook.
+ */
+export declare function installHostPackageAliases(aliases: Record<string, string>): Promise<() => void>;
+/**
+ * @param ctx cordis context
+ * @param config
+ */
+export declare function create(ctx: CordisContext, config?: HostAdapterConfig): HostAdapterType;
+interface HostAdapterType {
+    supports: string;
+    name: string;
+    apply: () => Promise<void>;
+    dispose: () => void;
+}
+export {};

package/lib/types/adapters/index.d.ts

@@ -0,0 +1,22 @@
+import type { AdapterFactory } from '../types.js';
+import type { AdapterRegistry } from '../registry.js';
+/** All host adapter factories, in registration order. */
+export declare const hostAdapters: AdapterFactory[];
+/** Register every built-in host adapter onto a registry. */
+export declare function registerHostAdapters(registry: AdapterRegistry): AdapterRegistry;
+export declare const clientAdapters: {
+    supports: string;
+    name: string;
+    moduleAliases: {
+        '@deepseek-ai/dsh-client-runtime/src/client/sessions/context-provenance.ts': string;
+        'dsh/runtime/context-provenance': string;
+    };
+    packageAliases: {
+        '@dsh-plugin/dsh-loader/ui-primitives': string;
+        '@dsh-plugin/dsh-loader/ui-slots': string;
+        '@dsh-plugin/dsh-loader/web-react': string;
+        '@dsh-plugin/dsh-loader/schema-form': string;
+        '@dsh-plugin/dsh-loader/ui-settings': string;
+        '@dsh-plugin/dsh-loader/runtime': string;
+    };
+}[];

package/lib/types/client-ui.d.ts

@@ -0,0 +1,40 @@
+import { type DshLoaderUi } from './ui/index.js';
+export * from './ui/index.js';
+export { createClientAPI, installClient, installSettingsFetchInterceptor, ModuleNotFoundError, } from './client.js';
+/** cordis plugin name (matches the npm package name and the bundle id). */
+export declare const name = "@dsh-plugin/dsh-loader";
+/** dshloader consumes no cordis service; it only provides. */
+export declare const inject: string[];
+/**
+ * The UI facade for callers that reach dshloader through the module table rather
+ * than `window.__dshLoader__`.
+ *
+ * @returns the facade, or `undefined` before the client plugin has applied.
+ */
+export declare function getUi(): DshLoaderUi | undefined;
+/**
+ * The cordis client service name dshloader publishes its UI facade under.
+ *
+ * Consumers should declare `inject: ['dshLoaderUi']` and read `ctx.dshLoaderUi`:
+ * cordis then activates them only after dshloader's client half has applied,
+ * which is the only ordering guarantee available on the browser side.
+ * `dsh.client.immediately` guarantees the bundle's factory is REGISTERED early,
+ * not that its `apply` has run — so a plugin that reads
+ * `window.__dshLoader__.ui` without injecting can observe `undefined`.
+ */
+export declare const UI_SERVICE = "dshLoaderUi";
+/** Minimal cordis client context surface this entry touches. */
+interface ClientContextLike {
+    get?: (name: string) => unknown;
+    effect?: (fn: () => unknown) => unknown;
+    provide?: (name: string, value: unknown) => unknown;
+}
+/**
+ * cordis client-plugin entry.
+ *
+ * Mounts the infrastructure first (so the `__ModuleLoader__` wrapper is in place
+ * before any sibling bundle materialises), then the UI facade, then publishes it
+ * both as the `dshLoaderUi` cordis service (ordered access) and on
+ * `window.__dshLoader__.ui` (ad-hoc access from non-cordis code).
+ */
+export declare function apply(ctx: ClientContextLike): void;

package/lib/types/client.d.ts

@@ -0,0 +1,156 @@
+/** Browser-only globals dshloader relies on (typed loosely so the module compiles without DOM lib). */
+type FetchImpl = (input: any, init?: any) => Promise<{
+    clone(): {
+        json(): any;
+    };
+    json(): any;
+}>;
+interface DshLoaderWindowLike {
+    fetch: FetchImpl;
+    location?: {
+        origin?: string;
+    };
+    Response?: new (body?: string, init?: {
+        status?: number;
+        headers?: Record<string, string>;
+    }) => any;
+    __ModuleLoader__?: {
+        load(handoff: {
+            id: string;
+            factory: (require: (spec: string) => any) => any;
+        }): unknown;
+    };
+    __DSHLOADER_VERSION__?: string;
+    __DSHLOADER_CONFIG__?: {
+        exposeAllNamespaces?: boolean;
+    };
+    __dshNativeRequire__?: (spec: string) => any;
+    __dshLoader__?: unknown;
+}
+declare global {
+}
+export declare class ModuleNotFoundError extends Error {
+    specifier: string;
+    constructor(specifier: string);
+}
+interface CreateClientAPIOpts {
+    dshVersion?: string;
+    adapterVersion?: string;
+    moduleAliases?: Record<string, string>;
+    packageAliases?: Map<string, string> | Record<string, string>;
+    requireImpl?: (spec: string) => any;
+    fetchBridge?: {
+        describe: () => Promise<any>;
+        write: (mode: string, payload: object) => Promise<any>;
+    };
+    clientCtx?: {
+        get?: (name: string) => any;
+    };
+}
+/**
+ * Build the `window.__dshLoader__` API object.
+ */
+export declare function createClientAPI(opts?: CreateClientAPIOpts): {
+    version: string;
+    dshVersion: string | undefined;
+    adapterVersion: string | undefined;
+    require(specifier: string): any;
+    registerModuleAlias(alias: string, target: string): void;
+    /**
+     * Register a package-name alias for the client module loader's
+     * require(). When a plugin's bundle calls require('@old/pkg-name'),
+     * the loader's wrapped require remaps it to '@new/pkg-name' before
+     * hitting the module table. This lets dsh rename client packages
+     * across versions without forcing plugin bundles to rebuild.
+     */
+    registerPackageAlias(oldName: string, newName: string): void;
+    /**
+     * Read a client-side cordis service by name.
+     * Proxies to `clientCtx.get(name)` — the same ctx.get plugins use
+     * inside their client `apply(ctx)`, but exposed through the stable
+     * dshloader surface so plugins don't depend on the cordis context
+     * shape directly.
+     *
+     * Only available when dshloader's client apply() received a ctx
+     * (cordis client boot). Returns undefined when ctx is not wired.
+     */
+    services: {
+        get(name: string): any;
+    };
+    rpc: {
+        settings: {
+            describe: () => Promise<any>;
+            update: (ns: string, section: unknown) => Promise<any>;
+            replace: (ns: string, section: unknown) => Promise<any>;
+            mutate: (ns: string, ops: unknown) => Promise<any>;
+        };
+    } | undefined;
+};
+interface InstallClientOpts {
+    window?: DshLoaderWindowLike;
+    dshVersion?: string;
+    exposeAllNamespaces?: boolean;
+    requireImpl?: (spec: string) => any;
+    hostBridgePrefix?: string;
+    packageAliases?: Record<string, string>;
+    clientCtx?: {
+        get?: (name: string) => any;
+    };
+}
+/**
+ * Install dshloader into a browser-like environment.
+ */
+export declare function installClient(opts?: InstallClientOpts): {
+    version: string;
+    dshVersion: string | undefined;
+    adapterVersion: string | undefined;
+    require(specifier: string): any;
+    registerModuleAlias(alias: string, target: string): void;
+    /**
+     * Register a package-name alias for the client module loader's
+     * require(). When a plugin's bundle calls require('@old/pkg-name'),
+     * the loader's wrapped require remaps it to '@new/pkg-name' before
+     * hitting the module table. This lets dsh rename client packages
+     * across versions without forcing plugin bundles to rebuild.
+     */
+    registerPackageAlias(oldName: string, newName: string): void;
+    /**
+     * Read a client-side cordis service by name.
+     * Proxies to `clientCtx.get(name)` — the same ctx.get plugins use
+     * inside their client `apply(ctx)`, but exposed through the stable
+     * dshloader surface so plugins don't depend on the cordis context
+     * shape directly.
+     *
+     * Only available when dshloader's client apply() received a ctx
+     * (cordis client boot). Returns undefined when ctx is not wired.
+     */
+    services: {
+        get(name: string): any;
+    };
+    rpc: {
+        settings: {
+            describe: () => Promise<any>;
+            update: (ns: string, section: unknown) => Promise<any>;
+            replace: (ns: string, section: unknown) => Promise<any>;
+            mutate: (ns: string, ops: unknown) => Promise<any>;
+        };
+    } | undefined;
+} | undefined;
+/**
+ * Fetch interceptor for settings namespace whitelist bypass (fix 5, path 2).
+ * Mirrors dsh-upstream-fixes/lib/client.js (127-223).
+ *
+ * - /api/settings.describe: merge non-whitelisted namespaces from the host
+ *   bridge into the official response (rpcId/official fields preserved).
+ * - /api/settings.{update,mutate,replace}: route writes for namespaces the
+ *   official proxy does NOT expose through the host bridge, and rebuild the
+ *   response envelope as `{ type: 'server-response', rpcId, result }` so the
+ *   official client can correlate the response with the request.
+ */
+export declare function installSettingsFetchInterceptor(win: DshLoaderWindowLike, bridgePrefix?: string): () => void;
+export declare const name = "@dsh-plugin/dsh-loader";
+export declare const inject: string[];
+export declare function apply(ctx: {
+    get?: (name: string) => any;
+}): void;
+export {};

package/lib/types/patch.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The dshloader PATCH protocol (`ctx.dshLoader.patch` / `__dshLoader__.patch`).
+ *
+ * Monkey-patching a host method or global is the only way to intervene in
+ * behaviour dsh exposes no extension point for. Three plugins in this family
+ * each hand-rolled the protocol and they did NOT agree:
+ *
+ *   - dsh-loader's own `Module._resolveFilename` hook  → identity-checked restore
+ *   - dsh-network-settings' `globalThis.fetch` wrapper → identity-checked restore
+ *   - dsh-better-sidebar's `workspaces.openPath` wrap  → UNCONDITIONAL restore
+ *
+ * The last one silently destroys a later plugin's wrapper when it disposes
+ * first, even though its own comment promised the opposite. This module is the
+ * single correct implementation; every patch site delegates here.
+ *
+ * The five guarantees:
+ *
+ *  1. RAW original — each patch captures EXACTLY the value present when it
+ *     installed (another plugin's wrapper when one is already there) and
+ *     restores that value verbatim, never a bound copy. This is what lets a
+ *     chain of wrappers survive disposal in any order.
+ *  2. Identity-checked restore — disposal only reverts the slot when it still
+ *     holds OUR wrapper. If somebody patched on top afterwards, we leave the
+ *     chain alone (reverting would delete their wrapper).
+ *  3. Re-apply safety — re-applying the same `id` recovers the true original
+ *     first, so HMR / repeated `apply()` can never nest a wrapper in itself.
+ *     This holds while our patch is the OUTERMOST one; if a foreign patch was
+ *     layered on top in between, re-applying chains instead (un-nesting a
+ *     middle wrapper is not possible without rebuilding the whole chain).
+ *  4. Cross-instance durability — slot bookkeeping lives in a WeakMap parked on
+ *     `globalThis` under a `Symbol.for` key, so a reloaded module instance still
+ *     sees the original captured by its predecessor. Targets are never mutated.
+ *  5. Loud misuse — patching a non-function method, or a missing target, throws
+ *     instead of silently no-op'ing.
+ *
+ * Pure and environment-agnostic: no DOM, no Node builtins, so the same module
+ * serves the host half and the browser half.
+ *
+ * @module @dsh-plugin/dsh-loader/patch
+ */
+/** A live patch, disposed through {@link PatchHandle.dispose}. */
+export interface PatchHandle {
+    /** Remove this patch when the slot still carries its wrapper (idempotent). */
+    dispose(): void;
+    /** Whether the target slot still carries this patch's wrapper. */
+    readonly active: boolean;
+    /** The raw value captured before any dshloader patch touched the slot. */
+    readonly original: unknown;
+}
+/** Options shared by every patch entry point. */
+export interface PatchOptions {
+    /**
+     * Stable patch id. Re-applying the same id on the same slot recovers the
+     * true original before re-wrapping (guarantee 3), so HMR cannot nest
+     * wrappers. Defaults to `'anonymous'` — pass a real id (`'<plugin>:<what>'`)
+     * for any patch that can be re-applied.
+     */
+    id?: string;
+}
+/**
+ * Patch one slot of `target`. The low-level primitive behind
+ * {@link PatchAPI.method} and {@link PatchAPI.global}.
+ *
+ * @param target - object owning the slot (a service instance, `globalThis`, …).
+ * @param key - property key to wrap.
+ * @param wrap - receives the value currently in the slot (the previous wrapper
+ *   when another patch is already installed — chaining is intended) and returns
+ *   the replacement.
+ * @param options - see {@link PatchOptions}.
+ * @returns the handle whose `dispose()` reverts this patch.
+ */
+export declare function patchSlot<T = unknown>(target: object, key: PropertyKey, wrap: (original: T) => T, options?: PatchOptions): PatchHandle;
+/** Whether a dshloader patch is currently installed on `target[key]`. */
+export declare function isPatched(target: object, key: PropertyKey): boolean;
+/** The patch id currently installed on `target[key]`, or `undefined`. */
+export declare function patchIdOf(target: object, key: PropertyKey): string | undefined;
+/** The stable `patch` facade exposed on the host and browser APIs. */
+export interface PatchAPI {
+    /**
+     * Wrap a method of a service / object.
+     *
+     * ```ts
+     * const handle = ctx.dshLoader.patch.method(
+     *   workspaces, 'openPath',
+     *   original => (path: string) => takeover(path) ?? original.call(workspaces, path),
+     *   { id: 'better-sidebar:openPath' },
+     * )
+     * ```
+     */
+    method<T extends object, K extends keyof T>(target: T, key: K, wrap: (original: T[K]) => T[K], options?: PatchOptions): PatchHandle;
+    /**
+     * Wrap a global function such as `fetch`. Defaults to `globalThis`; pass
+     * `scope` for `window` or a test double.
+     *
+     * ```ts
+     * ctx.dshLoader.patch.global('fetch',
+     *   original => (input, init) => original(rewrite(input), init),
+     *   { id: 'network-settings:fetch' })
+     * ```
+     */
+    global<T = unknown>(key: PropertyKey, wrap: (original: T) => T, options?: PatchOptions & {
+        scope?: object;
+    }): PatchHandle;
+    /** Low-level primitive; `method`/`global` are thin wrappers over it. */
+    slot<T = unknown>(target: object, key: PropertyKey, wrap: (original: T) => T, options?: PatchOptions): PatchHandle;
+    /** Whether a dshloader patch currently occupies `target[key]`. */
+    isPatched(target: object, key: PropertyKey): boolean;
+    /** The patch id currently occupying `target[key]`, if any. */
+    patchIdOf(target: object, key: PropertyKey): string | undefined;
+}
+/** Build the `patch` facade. Stateless — all bookkeeping is in the global registry. */
+export declare function createPatchAPI(): PatchAPI;

package/lib/types/registry.d.ts

@@ -0,0 +1,35 @@
+import type { AdapterFactory, AdapterSelection } from './types.js';
+interface DshVersionOptions {
+    profileDir?: string;
+    dshPkgPath?: string;
+    env?: typeof process.env;
+}
+export declare class UnsupportedDshVersionError extends Error {
+    kind?: string;
+    version?: string;
+    minSupported?: string | null;
+    constructor(message: string, opts?: {
+        kind?: string;
+        version?: string;
+        minSupported?: string | null;
+    });
+}
+export declare class InvalidVersionError extends Error {
+    version?: string;
+    constructor(message: string, opts?: {
+        version?: string;
+    });
+}
+/**
+ * Resolve the installed dsh version.
+ *
+ * @returns semver version string, or undefined when unreachable
+ */
+export declare function detectDshVersion(opts?: DshVersionOptions): string | undefined;
+export declare class AdapterRegistry {
+    adapters: AdapterFactory[];
+    constructor();
+    register(factory: AdapterFactory): this;
+    select(version: string): AdapterSelection;
+}
+export {};

package/lib/types/services/dsh-symbols.d.ts

@@ -0,0 +1,70 @@
+/** Node's `setTimeout` ceiling (2^31 - 1), used when dsh-timeout is unavailable. */
+export declare const NODE_MAX_TIMER_DELAY_MS = 2147483647;
+/** The raw modules this facade forwards to, as resolved at boot. */
+export interface DshSymbolModules {
+    tools?: {
+        defineTool?: unknown;
+        ToolArgsError?: unknown;
+    };
+    timeout?: {
+        deadline?: unknown;
+        MAX_TIMER_DELAY_MS?: number;
+    };
+    credentials?: {
+        credentialRef?: unknown;
+    };
+    subagent?: {
+        delegationDepthOf?: unknown;
+    };
+    compaction?: {
+        BasicCompactionEngine?: unknown;
+    };
+    llm?: {
+        BlockAssembler?: unknown;
+    };
+}
+/**
+ * Module-level dsh symbols, grouped by owning package.
+ *
+ * Types are deliberately loose (`any`-shaped call signatures): pinning dsh's
+ * internal shapes here would defeat the shim's purpose, exactly as
+ * `src/types.ts` explains for the service surfaces.
+ */
+export interface DshSymbolsAPI {
+    tools: {
+        /** `defineTool(definition)` — build a tool definition dsh's registry accepts. */
+        defineTool<T>(definition: T): T;
+        /** `ToolArgsError` — the error class dsh expects for invalid tool arguments. */
+        readonly ToolArgsError: new (messages: string[]) => Error;
+    };
+    timeout: {
+        /** `deadline(...)` — dsh's cancellation-aware deadline helper. */
+        deadline<T>(...args: any[]): T;
+        /** dsh's timer ceiling; falls back to Node's own 2^31-1 when unavailable. */
+        readonly MAX_TIMER_DELAY_MS: number;
+    };
+    credentials: {
+        /** `credentialRef(ref)` — brand a raw reference for `credentials.resolve`. */
+        credentialRef(ref: unknown): unknown;
+    };
+    subagent: {
+        /** `delegationDepthOf(agent)` — how deep a delegated agent sits. */
+        delegationDepthOf(agent: unknown): number;
+    };
+    compaction: {
+        /**
+         * `BasicCompactionEngine` — the base class a plugin subclasses to override
+         * `summarize`. Throws when unavailable, because a subclass declaration has
+         * no meaningful fallback.
+         */
+        readonly BasicCompactionEngine: new (...args: any[]) => any;
+    };
+    llm: {
+        /** `BlockAssembler` — dsh's streaming content-block assembler. */
+        readonly BlockAssembler: new (...args: any[]) => any;
+    };
+}
+/** Build the `ctx.dshLoader.dsh` facade over boot-resolved modules. */
+export declare function createDshSymbolsAPI(opts: {
+    modules?: DshSymbolModules;
+}): DshSymbolsAPI;

package/lib/types/services/llm.d.ts

@@ -0,0 +1,30 @@
+/** The `@deepseek-ai/dsh-llm` surface the facades forward to. */
+export interface LlmModule {
+    createUserMessage?: (input: unknown) => unknown;
+    deepFreeze?: <T>(value: T) => T;
+    /** Streaming content-block assembler; surfaced through `dshLoader.dsh.llm`. */
+    BlockAssembler?: unknown;
+}
+/** The `llm` facade exposed on the host API. */
+export interface LlmAPI {
+    /**
+     * Build one identified, frozen user-role message.
+     *
+     * @param input - complete content and source for a new user message.
+     * @returns the immutable message.
+     * @throws when `@deepseek-ai/dsh-llm` is unavailable — callers building a
+     *   message have no meaningful fallback, so this fails loudly rather than
+     *   handing back something the agent loop would reject.
+     */
+    createUserMessage(input: unknown): unknown;
+    /**
+     * Deep-freeze a value with dsh's own helper (so frozen-ness matches what the
+     * runtime expects). Falls back to `Object.freeze` on the top level when the
+     * module is unavailable.
+     */
+    deepFreeze<T>(value: T): T;
+}
+/** Build the `ctx.dshLoader.llm` facade. */
+export declare function createLlmAPI(opts: {
+    module?: LlmModule;
+}): LlmAPI;

package/lib/types/services/registry.d.ts

@@ -0,0 +1,144 @@
+import type { CordisContext } from '../types.js';
+/** A live tool definition as the tools registry holds it (shape kept loose on purpose). */
+export interface ToolDefinitionLike {
+    name?: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    execute?: (args: Record<string, unknown>, exec: unknown) => Promise<unknown>;
+    [key: string]: unknown;
+}
+/** One permission preset row as the `permissionPresets` table stores it. */
+export interface PermissionPresetLike {
+    sandbox: string;
+    approval: string;
+    name?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+/** The optional dsh modules the facades need, resolved once at boot. */
+export interface RegistryModules {
+    /** `@deepseek-ai/dsh-sandbox` — for `ESCALATION_TARGETS`. */
+    sandbox?: {
+        ESCALATION_TARGETS?: readonly string[];
+    };
+    /** `@deepseek-ai/dsh-permission-presets` — for `effectivePermissionPreset`. */
+    permissionPresets?: {
+        effectivePermissionPreset?: (events: readonly unknown[]) => string | undefined;
+    };
+    /**
+     * `@deepseek-ai/dsh-settings` — the settings facade DELEGATES to these rather
+     * than reimplementing them. `installSettingsSection` in particular carries
+     * real upstream behaviour (register `base` from the composition entry, point
+     * the source thunk at the resolved scope, fall back to the entry when the
+     * service goes away, all riding the scoped fiber); copying that into a shim
+     * would be a bug farm.
+     */
+    settings?: {
+        installSettingsSection?: (ctx: unknown, ns: unknown, schema: unknown, entry: unknown, hooks: unknown) => void;
+        settingsNamespace?: (id: string) => unknown;
+        SettingsConflictError?: new (...args: never[]) => Error;
+    };
+    /**
+     * `@deepseek-ai/dsh-llm` — message-construction helpers are MODULE-level
+     * exports, not service methods, so `services.get('llm')` cannot reach them.
+     */
+    llm?: import('./llm.js').LlmModule;
+    /** `@deepseek-ai/dsh-tools` — `defineTool` / `ToolArgsError` are module-level. */
+    tools?: {
+        defineTool?: unknown;
+        ToolArgsError?: unknown;
+    };
+    /** `@deepseek-ai/dsh-timeout` — `deadline` / `MAX_TIMER_DELAY_MS`. */
+    timeout?: {
+        deadline?: unknown;
+        MAX_TIMER_DELAY_MS?: number;
+    };
+    /** `@deepseek-ai/dsh-credentials` — `credentialRef`. */
+    credentials?: {
+        credentialRef?: unknown;
+    };
+    /** `@deepseek-ai/dsh-subagent` — `delegationDepthOf`. */
+    subagent?: {
+        delegationDepthOf?: unknown;
+    };
+    /** `@deepseek-ai/dsh-compaction-basic` — the `BasicCompactionEngine` base class. */
+    compaction?: {
+        BasicCompactionEngine?: unknown;
+    };
+}
+/**
+ * Load the optional dsh modules the facades proxy.
+ *
+ * The specifiers are held in variables so TypeScript does not try to resolve
+ * them at build time: dshloader declares no `@deepseek-ai/*` dependency, and
+ * these packages only exist in the dsh runtime that loads the profile.
+ *
+ * @returns whatever resolved; a missing module simply stays `undefined`.
+ */
+export declare function preloadRegistryModules(): Promise<RegistryModules>;
+/** Tool-registry accessors. */
+export interface ToolsRegistryAPI {
+    /** Every registered tool definition; `[]` when the registry shape is unreachable. */
+    list(): ToolDefinitionLike[];
+    /** One definition by tool name. */
+    get(name: string): ToolDefinitionLike | undefined;
+    /**
+     * Run `patcher` over every registered definition now and after every
+     * `tools/change`, so load order between this plugin and the tool plugins does
+     * not matter.
+     *
+     * A definition is handed to a given `id` at most once (a non-enumerable
+     * `Symbol.for` marker on the definition), which is what stops a `tools/change`
+     * storm from wrapping `execute` again and again.
+     *
+     * @param patcher - mutates one live definition; throwing is contained and logged.
+     * @param options.id - stable patch id, used for the once-per-definition marker.
+     * @returns a disposer that stops the replay (already-applied patches stay).
+     */
+    patchAll(patcher: (def: ToolDefinitionLike) => void, options: {
+        id: string;
+    }): () => void;
+}
+/** Sandbox-registry accessors. */
+export interface SandboxRegistryAPI {
+    /** The escalation modes escalation tools advertise; `[]` when unreachable. */
+    escalationTargets(): readonly string[];
+    /**
+     * Advertise one extra escalation mode (idempotent).
+     * @returns a disposer removing the mode again; a no-op when unreachable.
+     */
+    addEscalationTarget(mode: string): () => void;
+}
+/** Permission-preset registry accessors. */
+export interface PermissionPresetsRegistryAPI {
+    /** The live preset table, or `undefined` when the service is absent. */
+    table(): Record<string, PermissionPresetLike> | undefined;
+    /**
+     * Define a preset unless the key already exists (declaration in a
+     * `cordis.patch.yml` layer wins).
+     * @returns a disposer removing only a preset this call actually added.
+     */
+    define(key: string, preset: PermissionPresetLike): () => void;
+    /**
+     * Fold a session's effective permission-preset key from its event log.
+     * @returns the preset key, or `undefined` when the helper is unavailable.
+     */
+    effective(events: readonly unknown[]): string | undefined;
+}
+/** The `registry` facade exposed on the host API. */
+export interface RegistryAPI {
+    tools: ToolsRegistryAPI;
+    sandbox: SandboxRegistryAPI;
+    permissionPresets: PermissionPresetsRegistryAPI;
+}
+/**
+ * Build the `ctx.dshLoader.registry` facade.
+ *
+ * @param opts.ctx - the cordis context (services are read lazily, never cached,
+ *   so a service arriving later is still picked up).
+ * @param opts.modules - optional dsh modules from {@link preloadRegistryModules}.
+ */
+export declare function createRegistryAPI(opts: {
+    ctx: CordisContext;
+    modules?: RegistryModules;
+}): RegistryAPI;