@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/extensions-service.d.ts

@@ -0,0 +1,568 @@
+/**
+ * The HOST half of the extension-management surface (Settings → Model as Tool).
+ *
+ * This module implements {@link ModelToolsRemote} from `extensions-api.ts` and is
+ * deliberately WIRE-AGNOSTIC: it imports `node:*` and the published SDK, never DSH,
+ * never the client page, and never the generated Typert artifact. That boundary is
+ * what lets the same implementation be exercised by unit tests without a Context,
+ * by the plugin at `apply`, and by whatever transports the browser half uses.
+ *
+ * The governing rule is TRUTHFULNESS over convenience, because every field here is
+ * shown to an operator who is about to change what code their host runs:
+ *
+ * - `store` is `null` when no extension store is configured, rather than an empty
+ *   string that a caller could mistake for a mounted store.
+ * - `writable` is derived from a real access check on the store path and from the
+ *   store lock being readable, not assumed from "the config mentions a directory".
+ * - `installed` means a record exists in the store lock; `active` means the
+ *   persisted observation was made by THIS process; `integrity` is `unknown` when
+ *   the installed bytes could not be digested, never `unchanged` by default.
+ * - `reason` names the FIRST condition that prevents install/activation, so a UI
+ *   can show why an extension is not usable instead of guessing.
+ *
+ * INSTALLATION IS NOT ACTIVATION (EXT-07): `install` returns `active: false` and
+ * never calls the lifecycle. `enable`/`disable` are the only activation paths.
+ *
+ * FIRST-PARTY DEPENDENCIES (EXT-09): a source-directory install also supplies the
+ * SDK's dependency graph (`extension-dependencies.ts`), which resolves every
+ * declared runtime dependency from the host's own installed tree and refuses the
+ * install by name when one is missing. With the operator's preinstalled-content
+ * gate on, the resolved directory is copied by the SDK and recorded with
+ * `provenance: 'preinstalled'`; with it off (the default), the dependency is served
+ * as verified archive bytes and EXT-10's lifecycle-script refusal applies.
+ *
+ * PERSISTENCE, STATED HONESTLY:
+ *
+ * - Activation intent is durable through the SDK: `ExtensionLifecycle.activate`
+ *   writes `desiredActivation: 'active'` and `deactivate` writes `'inactive'` into
+ *   the profile state document, so a restart follows the operator's last toggle
+ *   even when nothing else persists.
+ * - The operator's `disabledExtensions` list is a CONFIG value (Settings form). This
+ *   service cannot write plugin config from the host: no config writer is injected.
+ *   It therefore keeps this process's toggles as an in-memory override, seeded from
+ *   `disabledExtensions`, and exposes `persistDisabledExtensions` as the seam a host
+ *   with a config writer supplies. Without that seam, a toggle is truthfully
+ *   reported as affecting this process only, and a `disable` survives restart via
+ *   the SDK's durable `desiredActivation: 'inactive'` while an `enable` of an id
+ *   still listed in config will be filtered by the restore gate on the next load.
+ *
+ * @module @try-works/dsh-tool-mode/extensions-service
+ */
+import { ExtensionStore, stagedInstallFromDirectory, type ExtensionLifecycle, type InstallDependencyGraph, type InstalledRecord, type LifecycleAuditEvent } from '@try-works/tool-mode-extension-sdk';
+import type { ExtensionInstallResult, ExtensionPrepareResult, ExtensionToggleResult, ExtensionToolToggleResult, ExtensionUninstallResult, ExtensionsDescribeResult, ModelToolsRemote } from './extensions-api.ts';
+import { type ApprovalDecision, type ApprovalRecord, type ApprovalRequestInput, type ApprovalStore } from './approval.ts';
+import type { AcquisitionSource } from './asset-acquisition.ts';
+import { type PrepareAssetsSurface } from './prepared-assets.ts';
+/**
+ * The default dependency-graph depth bound for BOTH install arms (task-116).
+ *
+ * The SDK default (3) is too shallow for real trees. Preinstalled packages are
+ * NOT leaves for graph purposes: after copying one, the SDK reads that package's
+ * own declared dependencies and enqueues them one level deeper, so a host-tree
+ * graph is walked exactly like a registry graph. The real onnxruntime-node tree
+ * reaches `define-data-property` at depth 4 and
+ * `onnxruntime-node -> global-agent -> globalthis -> define-properties ->
+ * has-property-descriptors -> es-define-property` at depth 5, so the bound is a
+ * property of the graph, not of the arm that supplied its bytes. The package
+ * count is a separate bound (see {@link DEFAULT_REGISTRY_DEPENDENCY_PACKAGES}).
+ */
+export declare const DEFAULT_REGISTRY_DEPENDENCY_DEPTH = 12;
+/**
+ * The default dependency-graph PACKAGE bound for BOTH install arms.
+ *
+ * The SDK default (64) is too small for the real engine trees: the
+ * `@huggingface/transformers` route (with sharp, protobufjs and the platform
+ * binaries) and both minilm packages exceeded it, refusing an install that every
+ * other bound would have admitted. Raising the cap does not loosen resolution —
+ * every node still has to come from operator-completed host content or verified
+ * registry bytes — and the depth bound still shapes the graph.
+ */
+export declare const DEFAULT_REGISTRY_DEPENDENCY_PACKAGES = 256;
+/**
+ * Exact dependency versions whose published tarballs ship their runtime
+ * artifacts and whose lifecycle scripts are not needed to run.
+ *
+ * These are admitted on the registry arm WITHOUT executing a lifecycle script.
+ * The package bytes are still integrity-verified and the package.json is left
+ * untouched. A version not listed here keeps EXT-10's refusal. This is a
+ * deliberately narrow prebuilt-content allowlist, not a script-execution gate.
+ */
+export declare const DEFAULT_TRUSTED_PREBUILT_DEPENDENCIES: readonly string[];
+/**
+ * Record that a restart refused an installed extension because its bytes changed.
+ *
+ * A restore that only LOGS the integrity failure leaves the previous profile row
+ * saying `active`, reserving the extension's tool names while nothing is published.
+ * This writes the truthful state first: failed, no tools.
+ */
+export declare function recordRestoreIntegrityFailure(store: ExtensionStore, extensionId: string): void;
+/** What the host can report about the shared harness model provider (declarative extensions). */
+export interface HarnessProviderStatus {
+    /** Whether a provider is composed and able to serve declarative extensions. */
+    readonly available: boolean;
+    /** Provider identity when available, for the satisfied reason. */
+    readonly provider?: string;
+    /** Model identity the provider serves, when known. */
+    readonly model?: string;
+    /**
+     * REQUIRED when `available` is false: why not, and the exact remediation.
+     *
+     * Used VERBATIM as the harness-model requirement reason (and the enable preflight
+     * message), so it must be operator-facing and name the configuration that fixes it.
+     */
+    readonly reason?: string;
+    /** What clears it; defaults to `config`. */
+    readonly action?: 'config' | 'none';
+}
+/** The lifecycle surface this service needs. Narrower than the class, so a test can double it. */
+export type ExtensionActivation = Pick<ExtensionLifecycle, 'stateOf' | 'activate' | 'deactivate' | 'uninstall' | 'setToolEnabled'>;
+/** The directory installer signature the service delegates to. */
+export type DirectoryInstaller = (options: Parameters<typeof stagedInstallFromDirectory>[0]) => ReturnType<typeof stagedInstallFromDirectory>;
+/** Every named refusal this service raises. */
+export type ExtensionsServiceErrorCode = 
+/** `install`/`enable`/`disable` need `config.extensionStore`; it is not configured. */
+'extension-store-unconfigured'
+/** A live-host uninstall of an ACTIVE extension must name `deactivate` explicitly. */
+ | 'extension-in-use'
+/** `install` had no explicit source and `config.extensionSourceDir` is not configured. */
+ | 'extension-source-unconfigured'
+/** The resolved source directory does not exist, or is not a directory. */
+ | 'extension-source-missing'
+/** The requested id is not a usable package identity (a path could escape the source root). */
+ | 'extension-id-invalid'
+/** The source package's own name is not the id that was requested. */
+ | 'extension-source-mismatch'
+/** The source directory does not contain a discoverable extension package. */
+ | 'extension-source-invalid'
+/** Source-directory installs are developer mode and must be allowed by configuration. */
+ | 'extension-source-directories-not-allowed'
+/** The integrity digest of the source or the installed copy could not be computed. */
+ | 'extension-digest-unavailable'
+/** The SDK installer refused or failed; its own named error is carried in the message. */
+ | 'extension-install-failed'
+/** A declared runtime dependency could not be resolved, verified or materialized. */
+ | 'extension-dependency-unsatisfied'
+/** The extension has no installed record in the store, so it cannot be activated. */
+ | 'extension-not-installed'
+/** The store lock or the profile state document is unreadable, so activation state cannot be trusted. */
+ | 'extension-store-unreadable'
+/** The host mounted no lifecycle (no store at load), so activation state cannot change. */
+ | 'extension-activation-unavailable'
+/** `activate` refused or failed; the SDK's named error is carried in the message. */
+ | 'extension-activation-failed'
+/** Activation is refused because a declared model's assets were never prepared. */
+ | 'extension-preparation-required'
+/** The host mounted no prepared-assets surface, so assets cannot be prepared here. */
+ | 'extension-preparation-unavailable'
+/** The preparation plan could not be resolved or its readiness could not be recorded. */
+ | 'extension-preparation-failed'
+/** A prerequisite the deployment cannot satisfy blocks activation before any lifecycle call. */
+ | 'extension-requirement-unmet'
+/** The extension's optional tool runtime is not installed, so its tools cannot load. */
+ | 'extension-runtime-unavailable'
+/** The asset lock declares no transferable location; preparation is not possible here. */
+ | 'extension-asset-source-unavailable'
+/** Registry mode was selected but no registry URL is configured. */
+ | 'extension-registry-unconfigured'
+/** The registry has no such package, version, or dist-tag (HTTP 404 / no matching version). */
+ | 'extension-registry-not-found'
+/** The registry metadata has no sha512 `dist.integrity`; unverified bytes are never installed. */
+ | 'extension-registry-integrity-missing'
+/** The registry metadata or tarball URL does not have the shape this host can verify. */
+ | 'extension-registry-invalid-metadata'
+/** The tarball could not be downloaded, or exceeds the configured byte cap. */
+ | 'extension-registry-fetch-failed'
+/** Transport failure or 5xx: the registry did not answer usefully. */
+ | 'extension-registry-unavailable'
+/** The fetched tarball does not hash to the registry-declared sha512. */
+ | 'extension-registry-integrity-mismatch'
+/** A URL source must carry a pinned `#sha512-...` integrity fragment. */
+ | 'extension-url-integrity-required'
+/** The URL tarball could not be fetched, redirected safely, or stayed within bounds. */
+ | 'extension-url-fetch-failed'
+/** The URL tarball does not hash to the pinned fragment. */
+ | 'extension-url-integrity-mismatch'
+/** `deactivate` refused or failed; the SDK's named error is carried in the message. */
+ | 'extension-deactivation-failed'
+/** The host's disabled-list writer rejected the new list after the action landed. */
+ | 'extension-override-persist-failed'
+/** SEC-09: the mutation needs an explicit operator approval (requested, approved and committed). */
+ | 'extension-approval-required';
+/**
+ * A named refusal from the extension-management surface.
+ *
+ * The `code` is stable and machine-readable; the message is operator-facing and
+ * names the concrete condition (path, SDK code, or identity) rather than a generic
+ * "failed", because the Settings page shows it verbatim.
+ */
+export declare class ExtensionsServiceError extends Error {
+    readonly name = "ExtensionsServiceError";
+    readonly code: ExtensionsServiceErrorCode;
+    constructor(code: ExtensionsServiceErrorCode, message: string, options?: ErrorOptions);
+}
+/** The host's disabled-list store. `list` is read live; `set` is called after a toggle. */
+export interface ExtensionsServiceOptions {
+    /** `config.extensionStore`; empty means no extension store is configured. */
+    readonly storeDir?: string;
+    /**
+     * `config.extensionSourceDir`: the directory that holds first-party package
+     * checkouts, one directory per package. Empty means no source directory.
+     */
+    readonly sourceDir?: string;
+    /**
+     * `config.extensions.allowSourceDirectories`: the explicit developer-mode gate.
+     * Absent/false refuses every directory install with a named error.
+     */
+    readonly allowSourceDirectories?: boolean;
+    /** The lifecycle profile; defaults to `default`, the profile the host restores. */
+    readonly profile?: string;
+    /** Read `config.disabledExtensions` live. */
+    readonly disabledExtensions?: () => readonly string[];
+    /**
+     * Persist the effective disabled list. The host's implementation must arrange for
+     * `disabledExtensions()` to return the same list afterwards; a rejection is
+     * surfaced as `extension-override-persist-failed`.
+     */
+    readonly persistDisabledExtensions?: (ids: readonly string[]) => void | Promise<void>;
+    /**
+     * The mounted lifecycle, read lazily. Absent means the host mounted none, and
+     * `enable`/`disable` refuse with `extension-activation-unavailable` instead of
+     * pretending the durable state changed.
+     */
+    readonly lifecycle?: () => ExtensionActivation | undefined;
+    /**
+     * SEC-09: the approval state machine, read lazily.
+     *
+     * When mounted, a management-sensitive mutation (currently extension ACTIVATION)
+     * requires an explicit operator decision: `enable` records a PENDING request and
+     * refuses, and the mutation happens only through `commitApproval`, which consumes
+     * the approval exactly once. Absent means the composition carries an operator
+     * pre-approval path and the direct calls keep their existing behavior — a
+     * documented compatibility path, not a silent bypass: a host that mounts this seam
+     * cannot mutate without a committed approval.
+     */
+    readonly approvals?: () => ApprovalStore | undefined;
+    /**
+     * Why the startup asset walk could not rebuild an extension's prepared handles, if
+     * it could not. The host writes this from its restore pass; the row must not show
+     * "needs its model assets prepared" with no explanation when the REAL reason is a
+     * cache file that is absent or a different size. Absent means the walk succeeded or
+     * never ran for that extension.
+     */
+    readonly assetRestoreDiagnostic?: (extensionId: string) => string | undefined;
+    /** Declare that this host cannot write the store (read-only mount). */
+    readonly readOnly?: boolean;
+    /** Receive install/prepare lifecycle outcomes (EXT-35); activate/deactivate/uninstall come from the SDK. */
+    readonly onAudit?: (event: LifecycleAuditEvent) => void;
+    /**
+     * How an install without an explicit source directory is sourced.
+     *
+     * - `registry` (and `auto`, the default) resolve the package from the npm registry.
+     * - `directory` keeps the developer-mode source-directory path.
+     * - `auto` additionally falls back to the directory ONLY for a TRANSPORT-level
+     *   registry failure (unreachable/timeout/5xx) and only when
+     *   `allowSourceDirectories` is on; a package-level refusal (404, missing
+     *   integrity, bad tarball, digest mismatch) is always named and never retried
+     *   against a local directory.
+     */
+    readonly installSource?: 'registry' | 'directory' | 'auto';
+    /** The npm registry base URL; defaults to the public npm registry. */
+    readonly registryUrl?: string;
+    /** Hard cap on one registry package tarball; defaults to the SDK archive bound (256 MiB). */
+    readonly registryTarballMaxBytes?: number;
+    /** Packument/metadata timeout in ms. Defaults to 30 s; slow registries may raise it. */
+    readonly registryMetadataTimeoutMs?: number;
+    /**
+     * IDLE timeout for one registry tarball download, in ms; defaults to 10 minutes.
+     *
+     * Separate from the short metadata timeout: onnxruntime-node is hundreds of MB,
+     * and a moving transfer must not be aborted by the packument budget. Aborts only
+     * when NO bytes arrive for this long; the byte cap remains the real bound.
+     */
+    readonly registryTarballTimeoutMs?: number;
+    /**
+     * Dependency-graph depth bound for BOTH install arms; defaults to
+     * {@link DEFAULT_REGISTRY_DEPENDENCY_DEPTH} (12). Configurable because real
+     * dependency trees vary; a refusal names the level and the package. The name is
+     * historical: the source-directory arm needs the bound too, because the SDK
+     * walks a preinstalled package's declared dependencies exactly like registry
+     * bytes.
+     */
+    readonly registryDependencyDepth?: number;
+    /**
+     * Dependency-graph PACKAGE bound for BOTH install arms; defaults to
+     * {@link DEFAULT_REGISTRY_DEPENDENCY_PACKAGES} (256). The depth bound decides
+     * how deep the graph may go; this decides how WIDE it may become.
+     */
+    readonly registryDependencyPackages?: number;
+    /** INTERNAL TEST SEAM: the directory installer, defaulting to the SDK's staged path. */
+    readonly installDirectory?: DirectoryInstaller;
+    /** INTERNAL TEST SEAM: the content digest, defaulting to the SDK's installed-content digest. */
+    readonly digestContent?: (directory: string) => string;
+    /**
+     * INTERNAL TEST SEAM: the dependency graph for a first-party source checkout.
+     *
+     * The default resolves each declared dependency from the host's own installed
+     * tree (`extension-dependencies.ts`) and refuses the install, by name, when one
+     * is not installed or is inadmissible. The graph is part of the same
+     * developer-mode source-directory gate; it is never consulted for anything else.
+     */
+    readonly dependencyGraph?: (sourcePackageDir: string) => InstallDependencyGraph;
+    /**
+     * Operator gate for PREINSTALLED dependency content (task-84); DEFAULT OFF.
+     *
+     * When on, a dependency resolved from the host's installed tree is copied by the
+     * SDK into the extension's own install directory and recorded with
+     * `provenance: 'preinstalled'` — the content arrived from an operator-completed
+     * install and this installer ran no lifecycle script. When off, the bytes arm
+     * applies and EXT-10's script refusal is unchanged. Requires
+     * {@link ExtensionsServiceOptions.preinstalledDependenciesRoot}.
+     */
+    readonly allowPreinstalledDependencies?: boolean;
+    /** The operator-configured root preinstalled dependency directories must live under. */
+    readonly preinstalledDependenciesRoot?: string;
+    /**
+     * Exact `name@version` packages whose published tarball ships prebuilt runtime
+     * artifacts. Their lifecycle-script declarations are admitted but NEVER run.
+     * Defaults to {@link DEFAULT_TRUSTED_PREBUILT_DEPENDENCIES}; an empty array
+     * restores the strict EXT-10 refusal for every package.
+     */
+    readonly trustedPrebuiltDependencies?: readonly string[];
+    /**
+     * The mounted prepared-assets surface, read lazily (the plugin constructs it in
+     * `apply` after this service). Absent means the host mounted no asset surface,
+     * and `prepare` refuses with `extension-preparation-unavailable`.
+     */
+    readonly prepareSurface?: () => PrepareAssetsSurface | undefined;
+    /**
+     * The acquisition source a preparation uses. Defaults to the real ranged HTTP
+     * source; a test injects a local source and the suite therefore performs no
+     * network.
+     */
+    readonly preparationSource?: () => AcquisitionSource;
+    /**
+     * Read the operator's STANDING RES-02 approval for executable assets.
+     *
+     * DEFAULT FALSE. When false, `prepare` passes `allowExecutable: false` and the
+     * prepared-assets registry returns its exact refusal without acquiring anything.
+     * When the operator explicitly configured the approval, that is the standing
+     * consent for the digest-pinned plans this host resolves; the management channel
+     * (`extensions-prepare`) still takes its own PER-CALL flag and is unaffected.
+     */
+    readonly allowExecutablePreparation?: () => boolean;
+    /**
+     * Read the host's harness-model provider status (task-93 seam).
+     *
+     * Consulted only for `execution.kind === 'declarative'` extensions, which are
+     * served by the host's harness broker and therefore need a composed LlmProvider.
+     * Absent means the host cannot answer; the harness-model requirement is then
+     * reported unsatisfied with an honest "provider status unknown" reason.
+     */
+    readonly harnessProviderStatus?: () => HarnessProviderStatus | undefined;
+    /**
+     * Notified when this service changes an extension's activation intent.
+     *
+     * The host's contribution registrar refuses to publish a tool for an extension
+     * absent from its activated set, so a runtime `enable` must admit the id BEFORE
+     * the lifecycle publishes and revoke it when activation fails or the extension is
+     * disabled. The host implementations may reconcile against the lifecycle state.
+     */
+    readonly onActivationChange?: (extensionId: string, active: boolean) => void;
+}
+/**
+ * The directory a first-party checkout for one package identity occupies.
+ *
+ * A source directory holds PACKAGE DIRECTORIES, not scoped directories: the
+ * workspace layout is `packages/extension-laya`, whose package name is
+ * `@try-works/extension-laya`. The scope is therefore dropped and the final path
+ * segment is used, which is the only mapping that requires no registry lookup.
+ * @param extensionId - the extension identity, which equals its package name.
+ * @returns the directory name under the configured source directory.
+ */
+export declare function packageDirFor(extensionId: string): string;
+/**
+ * Select the current installed record for one identity.
+ *
+ * The EXT-30 active-version pointer wins when it names an installed version; a
+ * store without pointers (the pre-update world) uses the last recorded version,
+ * which is the order `recordInstall` appends in.
+ * @param records - every installed record.
+ * @param activeVersions - the EXT-30 pointer map.
+ * @param extensionId - the identity to select.
+ * @returns the selected record, or undefined when nothing is installed for the id.
+ */
+export declare function selectInstalled(records: readonly InstalledRecord[], activeVersions: Readonly<Record<string, string>>, extensionId: string): InstalledRecord | undefined;
+/**
+ * The extension-management service: describe, install, enable, disable.
+ *
+ * Construct one per host and share it between the wire transport and any local
+ * surface; it owns the in-process override list and must not be duplicated, or two
+ * instances would report different disabled sets.
+ */
+export declare class ExtensionsService implements ModelToolsRemote {
+    #private;
+    constructor(options?: ExtensionsServiceOptions);
+    /**
+     * Read the current state of the extension surface.
+     *
+     * Every row is derived from the store, the profile state and the source
+     * directory; nothing is cached between calls, so a page that re-reads after an
+     * action sees the committed result.
+     * @param signal - cancellation.
+     * @returns the store/source configuration and one row per known extension.
+     */
+    describe(signal?: AbortSignal): Promise<ExtensionsDescribeResult>;
+    /**
+     * Describe identity, state and tools WITHOUT digesting installed bytes.
+     *
+     * The Tool Insights inventory and owner attribution do not render integrity;
+     * on a deployment with multi-GB extension trees the digest pass otherwise
+     * stalls the Remote gateway for every inventory read.
+     * @param signal - cancellation.
+     * @returns the same row shape, with integrity reported as `unknown`.
+     */
+    describeFast(signal?: AbortSignal): Promise<ExtensionsDescribeResult>;
+    /**
+     * Install one extension, choosing the route from the operator configuration.
+     *
+     * - An EXPLICIT `source` path is always a developer-mode directory install (the
+     *   existing source-directory gate and refusals apply).
+     * - Otherwise `installSource` decides. `registry` resolves `id@latest` from the
+     *   npm registry. `directory` uses the configured source directory. `auto` (the
+     *   default) prefers the registry and falls back to the directory ONLY for a
+     *   transport-level registry failure (unreachable/timeout/5xx) when directory
+     *   installs are allowed — a package-level refusal (404, missing integrity, bad
+     *   tarball, digest mismatch) is always named and never retried locally.
+     *
+     * INSTALLATION IS NOT ACTIVATION: the result is always `active: false`, and it
+     * names the route that actually supplied the bytes.
+     * @param extensionId - the package identity to install.
+     * @param source - an explicit source directory (developer override), or absent.
+     * @param signal - cancellation.
+     * @returns the installed identity, version and route.
+     * @throws ExtensionsServiceError for every refusal and failure.
+     */
+    install(extensionId: string, source?: string, signal?: AbortSignal): Promise<ExtensionInstallResult>;
+    /**
+     * Whether a hostname is a local/private/metadata destination (EXT-11).
+     *
+     * A caller-supplied source URL is itself explicit authorization for that destination.
+     * A REDIRECT from a public source into one of these ranges is not: it would turn an
+     * approved public URL into a local-network or cloud-metadata fetch.
+     * @param hostname - the URL hostname.
+     * @returns true for loopback, RFC1918, link-local, ULA and metadata hosts.
+     */
+    static isPrivateDestination(hostname: string): boolean;
+    /**
+     * Activate an installed extension and clear its disabled override.
+     *
+     * Activation runs through the mounted lifecycle, which verifies the installed
+     * bytes, publishes the contributions and persists `desiredActivation: 'active'`.
+     * The disabled list is updated only after activation succeeds, so a refused
+     * activation does not leave the operator's override claiming a state change that
+     * did not happen.
+     *
+     * With an approval store mounted (`approvals`), this method does NOT activate: it
+     * records a pending `extension-activate` request and refuses, and only
+     * `commitApproval` applies the mutation. Without one, the direct path is the
+     * documented pre-approved compatibility composition.
+     * @param extensionId - the installed extension.
+     * @param signal - cancellation.
+     * @returns the id with the observed active/disabled state.
+     * @throws ExtensionsServiceError for every refusal.
+     */
+    enable(extensionId: string, signal?: AbortSignal): Promise<ExtensionToggleResult>;
+    /**
+     * Record a pending approval for one management-sensitive mutation (SEC-09).
+     *
+     * The seam is REQUIRED here: creating a record on a host that mounted no store
+     * would hand the operator an approval nothing can commit — the dead end this
+     * wiring exists to remove.
+     * @param input - the request facts (kind, exact scope, operator, reason, optional TTL).
+     * @returns the pending record (a plain-JSON copy).
+     * @throws ExtensionsServiceError when no approval store is mounted; ApprovalError for a bad request.
+     */
+    requestApproval(input: ApprovalRequestInput): ApprovalRecord;
+    /**
+     * Apply an explicit operator decision to a request (SEC-09).
+     *
+     * Decisions are the operator's alone; this method only forwards one, and the store
+     * enforces that repeating the SAME decision is idempotent while the opposite
+     * decision after a decision is refused.
+     * @param id - the approval id.
+     * @param decision - approve or deny, who decided, and an optional note.
+     * @returns the decided record.
+     * @throws ApprovalError for an unknown/expired/committed request or a conflicting decision.
+     */
+    decideApproval(id: string, decision: ApprovalDecision): ApprovalRecord;
+    /**
+     * Consume an approved activation and apply it EXACTLY once.
+     *
+     * Order is deliberate: the approval is consumed — and its scope checked against
+     * `extensionId` by the store — BEFORE any mutation, so a wrong-scope or replayed
+     * commit cannot touch the operator's extension. The store's one-shot commit is the
+     * exactly-once guarantee; a second call is `approval/already-committed` and never
+     * reaches the lifecycle. A mutation that fails AFTER the commit leaves the approval
+     * spent: the operator re-requests rather than replaying an approval whose
+     * conditions may have changed.
+     * @param id - the approval id.
+     * @param extensionId - the exact extension the caller is about to activate.
+     * @param signal - cancellation.
+     * @returns the activation result.
+     * @throws ApprovalError for a pending/denied/expired/committed/mismatched approval.
+     * @throws ExtensionsServiceError for the activation's own refusals.
+     */
+    commitApproval(id: string, extensionId: string, signal?: AbortSignal): Promise<ExtensionToggleResult>;
+    /** Live per-tool toggle through the running host (EXT-31 settings action). */
+    setToolEnabled(extensionId: string, toolName: string, enabled: boolean, signal?: AbortSignal): Promise<ExtensionToolToggleResult>;
+    /** Live uninstall; an active extension requires explicit deactivation (EXT-31 settings action). */
+    uninstall(extensionId: string, deactivate?: boolean, signal?: AbortSignal): Promise<ExtensionUninstallResult>;
+    /**
+     * Acquire and verify an installed extension's model assets, then record the
+     * resulting readiness.
+     *
+     * This is the management-channel `extensions-prepare-plan` + `extensions-prepare`
+     * pair behind one call, over the SAME host surface: the plan is resolved from the
+     * installed manifest's asset lock, the acquisition runs through the injectable
+     * source (the real ranged HTTP source unless the host injects one), and a
+     * successful acquisition records `prepared-cold` through the lifecycle — which is
+     * what lets a following `enable` activate the extension.
+     *
+     * Success is reported ONLY when that readiness was actually recorded for the
+     * planned deployment. The acquisition and the readiness are two different facts,
+     * and they can disagree (a surface whose readiness write did not land, a host
+     * that never mounted the lifecycle, an installed build the assets cannot make
+     * callable); reporting `prepared: true` there is what makes Prepare look like a
+     * no-op, because the page celebrates while the row keeps its blocker.
+     *
+     * The RES-02 executable gate is deliberately CLOSED here: the Remote call carries
+     * no executable-approval argument, so a plan containing an executable asset is
+     * returned as `prepared: false` with the registry's own reason rather than
+     * acquired. The pinned EmbeddingGemma assets are not executable.
+     * @param extensionId - the installed extension to prepare.
+     * @param signal - cancellation.
+     * @returns the disclosure that was executed and the resulting readiness.
+     * @throws ExtensionsServiceError for every precondition and plan failure.
+     */
+    prepare(extensionId: string, signal?: AbortSignal): Promise<ExtensionPrepareResult>;
+    /**
+     * Deactivate an installed extension and record it as disabled.
+     *
+     * The SDK's deactivation persists `desiredActivation: 'inactive'` BEFORE it
+     * withdraws anything, so the durable answer survives a crash mid-withdrawal. The
+     * disabled override is recorded only after the lifecycle call settles; a
+     * deactivation that throws leaves the operator's list unchanged.
+     * @param extensionId - the installed extension.
+     * @param signal - cancellation.
+     * @returns the id with the observed active/disabled state.
+     * @throws ExtensionsServiceError for every refusal.
+     */
+    disable(extensionId: string, signal?: AbortSignal): Promise<ExtensionToggleResult>;
+}
+/**
+ * Construct the extension-management service.
+ * @param options - store/source configuration and the host's seams.
+ * @returns a service satisfying {@link ModelToolsRemote}.
+ */
+export declare function createExtensionsService(options?: ExtensionsServiceOptions): ExtensionsService;
+//# sourceMappingURL=extensions-service.d.ts.map

package/lib/extensions-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions-service.d.ts","sourceRoot":"","sources":["../src/extensions-service.ts"],"names":[],"mappings":"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"}