@try-works/dsh-model-as-tool 0.1.2 → 0.3.6

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/runtime-link.js

@@ -0,0 +1,149 @@
+/**
+ * Make the runtime SDK resolvable from inside an installed extension (EXT-02, EXT-19).
+ *
+ * THE GAP THIS CLOSES. Installing a package puts it at
+ * `<store>/extensions/<id>/<version>/`, which has no `node_modules`. An extension that
+ * declares `@try-works/tool-mode-extension-sdk` — which is what the extension protocol
+ * requires it to depend on — therefore cannot import it, and its entry fails with
+ * `ERR_MODULE_NOT_FOUND`. The package is discoverable and activatable and cannot RUN.
+ *
+ * This is the same class of problem the host hit when its own dependency was unpublished:
+ * a package is only loadable where its dependencies resolve. The store has no install step,
+ * so the link has to be made deliberately.
+ *
+ * WHY A DIRECTORY LINK RATHER THAN A COPY. The SDK is HOST-PROVIDED and versioned with the
+ * host, so copying it into every install would ship N copies that drift independently — and
+ * an extension running against a stale copy of the runtime is worse than one that refuses
+ * to start. The link keeps a single implementation.
+ *
+ * A JUNCTION ON WINDOWS: `symlinkSync` with a `'dir'` type needs elevation, while a
+ * junction does not, and junctions are the realistic Windows case in this repository's
+ * other escape tests for the same reason.
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/runtime-link
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+/** The one runtime dependency an extension is allowed to have (EXT-02). */
+export const RUNTIME_SDK_NAME = '@try-works/tool-mode-extension-sdk';
+/**
+ * Locate this package's own root.
+ *
+ * Resolved from the SDK itself rather than from the caller, so the link points at the
+ * runtime the INSTALLER is running from — the one that will actually execute the extension.
+ * @returns the absolute package root, or undefined when it cannot be found.
+ */
+export function runtimeSdkRoot() {
+    try {
+        const require = createRequire(import.meta.url);
+        // `package.json` rather than the entry, because the ROOT is what must be linked and the
+        // entry may be remapped by an exports condition.
+        return dirname(require.resolve(`${RUNTIME_SDK_NAME}/package.json`));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Make the runtime SDK resolvable from an installed extension.
+ *
+ * @param installPath - the installed package directory.
+ * @param sdkRoot - where the runtime lives; resolved automatically when omitted.
+ * @returns what happened, which is reported rather than assumed.
+ */
+export function linkRuntimeSdk(installPath, sdkRoot = runtimeSdkRoot()) {
+    if (sdkRoot === undefined) {
+        /**
+         * NOT FATAL. An extension that imports nothing (a declarative or tool-only package)
+         * runs fine without the link, so refusing the whole install would break working
+         * packages to fix a problem they do not have.
+         */
+        return { linked: false, reason: 'sdk-not-locatable' };
+    }
+    const scopeDirectory = join(installPath, 'node_modules', '@try-works');
+    const linkPath = join(scopeDirectory, 'tool-mode-extension-sdk');
+    /**
+     * A PRE-EXISTING ENTRY IS NOT ASSUMED TO BE OURS.
+     *
+     * This was a real, reproduced escape. The first version returned `already-present` if
+     * ANYTHING existed at the link path — and an archive may legitimately SHIP that
+     * directory, because nothing about it is a traversal or an illegal name. The installer
+     * then never made the host link, and Node resolved the extension's bare
+     * `import '@try-works/tool-mode-extension-sdk'` to the PACKAGE-SUPPLIED module. The
+     * package was executing against its own copy of the runtime, and the operator was told
+     * the link was "already-present", which reads as success.
+     *
+     * The check is now on the CONTENT, not the existence: the entry must be the same package
+     * at the same version as the runtime the installer is running from. Anything else is
+     * refused, and refusal is the right answer rather than replacement — silently deleting
+     * files an archive shipped would make the installed bytes differ from the verified
+     * digest the operator approved.
+     */
+    if (existsSync(linkPath)) {
+        const shipped = readPackageIdentity(linkPath);
+        const ours = readPackageIdentity(sdkRoot);
+        if (shipped === undefined || ours === undefined || shipped.name !== ours.name || shipped.version !== ours.version) {
+            return {
+                linked: false,
+                reason: 'sdk-shadowed',
+                path: linkPath,
+                detail: `the package ships its own ${RUNTIME_SDK_NAME}`
+                    + `${shipped === undefined ? ' (unreadable)' : `@${shipped.version}`}, `
+                    + `but the host provides ${ours === undefined ? 'an unreadable runtime' : `@${ours.version}`}. `
+                    + 'An extension must run against the host runtime, so this install is refused.',
+            };
+        }
+        return { linked: false, reason: 'already-present', path: linkPath, detail: `the host runtime @${ours.version} is already linked` };
+    }
+    try {
+        mkdirSync(scopeDirectory, { recursive: true });
+        /**
+         * A junction, which on Windows does not require elevation. `type` is ignored on POSIX,
+         * where this becomes a plain directory symlink.
+         */
+        symlinkSync(sdkRoot, linkPath, 'junction');
+        return { linked: true, path: linkPath };
+    }
+    catch (error) {
+        // Clean up a half-made link so a retry is not blocked by a broken entry.
+        rmSync(linkPath, { recursive: true, force: true });
+        return {
+            linked: false,
+            reason: 'link-failed',
+            path: linkPath,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** Read a package's name and version, or undefined when it cannot be read. */
+function readPackageIdentity(packageRoot) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+        if (typeof manifest.name !== 'string' || typeof manifest.version !== 'string')
+            return undefined;
+        return { name: manifest.name, version: manifest.version };
+    }
+    catch {
+        // An unreadable or absent manifest is NOT an identity match. A planted directory with
+        // a broken manifest must not be treated as the host runtime.
+        return undefined;
+    }
+}
+/**
+ * Remove a runtime link, for an uninstall (EXT-24).
+ *
+ * Removed separately from the package directory so a caller that removes the link but keeps
+ * the package — or the reverse — does not end up with an extension whose imports resolve
+ * against a runtime it was not installed for.
+ * @param installPath - the installed package directory.
+ * @returns whether a link was removed.
+ */
+export function unlinkRuntimeSdk(installPath) {
+    const linkPath = join(installPath, 'node_modules', '@try-works', 'tool-mode-extension-sdk');
+    if (!existsSync(linkPath))
+        return false;
+    rmSync(linkPath, { recursive: true, force: true });
+    return true;
+}
+//# sourceMappingURL=runtime-link.js.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/source-directory.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Local source-directory developer mode (EXT-06's optional fourth source).
+ *
+ * A source DIRECTORY is treated as a package source with the SAME discipline
+ * as archives: the operator configuration must explicitly allow it, the path's
+ * ancestor chain is reparse-point-checked, the tree is COPIED (a source
+ * checkout is mutable and must not become a live installation), reparse points
+ * INSIDE the tree are refused, the manifest is validated exactly like a packed
+ * package, install-time lifecycle scripts are refused (never run), and the
+ * installation lands INACTIVE with its source recorded. It is developer mode,
+ * not a production release path (EXT-06: "Optional developer mode only").
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/source-directory
+ */
+import { type InstallPreview, type InstallProvenance, type StagedInstallResult } from './staged.ts';
+import { type InstallDependencyGraph } from './dependencies.ts';
+/**
+ * Install a local source directory in developer mode (EXT-06).
+ *
+ * @param options - the directory, the store, the operator allow-gate, and the
+ *   same preview/dependency/provenance options the archive path takes.
+ * @returns the installed (INACTIVE) extension.
+ * @throws ManagementError for every rejection path.
+ */
+export declare function stagedInstallFromDirectory(options: {
+    readonly sourceDir: string;
+    readonly storeDir: string;
+    /** The operator config gate: source directories install ONLY when explicitly allowed. */
+    readonly allowSourceDirectories: boolean;
+    readonly preview?: (preview: InstallPreview) => void | Promise<void>;
+    readonly dependencies?: InstallDependencyGraph;
+    readonly provenance?: InstallProvenance;
+    readonly record?: boolean;
+}): Promise<StagedInstallResult>;
+//# sourceMappingURL=source-directory.d.ts.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/source-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-directory.d.ts","sourceRoot":"","sources":["../../src/install/source-directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,EAAkB,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACnH,OAAO,EAAgD,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AA6D7G;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yFAAyF;IACzF,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAA;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAA;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAA;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA2H/B"}

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/source-directory.js

@@ -0,0 +1,179 @@
+/**
+ * Local source-directory developer mode (EXT-06's optional fourth source).
+ *
+ * A source DIRECTORY is treated as a package source with the SAME discipline
+ * as archives: the operator configuration must explicitly allow it, the path's
+ * ancestor chain is reparse-point-checked, the tree is COPIED (a source
+ * checkout is mutable and must not become a live installation), reparse points
+ * INSIDE the tree are refused, the manifest is validated exactly like a packed
+ * package, install-time lifecycle scripts are refused (never run), and the
+ * installation lands INACTIVE with its source recorded. It is developer mode,
+ * not a production release path (EXT-06: "Optional developer mode only").
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/source-directory
+ */
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join, parse, resolve, sep } from 'node:path';
+import { ManagementError } from "./../errors.js";
+import { discoverExtension } from "./../discovery.js";
+import { digestInstalledContent, ExtensionStore } from "./store.js";
+import { installPathFor } from "./staged.js";
+import { installDependencyGraph, refuseInstallScripts } from "./dependencies.js";
+import { linkRuntimeSdk, RUNTIME_SDK_NAME } from "./runtime-link.js";
+/** The dev-mode bounds for one directory copy. */
+const MAX_DIRECTORY_FILES = 10_000;
+const MAX_DIRECTORY_BYTES = 512 * 1024 * 1024;
+/** Refuse a reparse point anywhere on the source directory's ancestor chain. */
+function ancestorRefusal(target) {
+    const absolute = resolve(target);
+    const root = parse(absolute).root;
+    const components = absolute.slice(root.length).split(sep).filter(Boolean);
+    let cursor = root;
+    for (const component of components) {
+        cursor = join(cursor, component);
+        try {
+            if (lstatSync(cursor).isSymbolicLink()) {
+                return `the source directory passes through a symbolic link or junction at ${cursor}; developer-mode installs refuse reparse points`;
+            }
+        }
+        catch {
+            break;
+        }
+    }
+    return undefined;
+}
+/** Copy one directory tree, refusing reparse points and bounding the copy. */
+function copyTree(source, destination, budget) {
+    mkdirSync(destination, { recursive: true });
+    for (const entry of readdirSync(source, { withFileTypes: true })) {
+        const from = join(source, entry.name);
+        const to = join(destination, entry.name);
+        if (entry.isSymbolicLink() || entry.isFile() === false && entry.isDirectory() === false) {
+            // Windows junctions appear as symlinks via dirent in modern Node;
+            // anything that is neither a plain file nor a directory is refused.
+            throw new ManagementError('INVALID_EXTENSION', 'install', `${from} is a reparse point; a source checkout must not smuggle links into the installation`, 'Remove the link or copy the referenced content explicitly; the installer never follows it.');
+        }
+        if (entry.isDirectory()) {
+            copyTree(from, to, budget);
+            continue;
+        }
+        const stat = lstatSync(from);
+        budget.files += 1;
+        budget.bytes += stat.size;
+        if (budget.files > MAX_DIRECTORY_FILES || budget.bytes > MAX_DIRECTORY_BYTES) {
+            throw new ManagementError('INVALID_EXTENSION', 'install', `the source directory exceeds the developer-mode bounds (${MAX_DIRECTORY_FILES} files / ${MAX_DIRECTORY_BYTES} bytes)`, 'Reduce the checkout or pack it into an archive.');
+        }
+        copyFileSync(from, to);
+    }
+}
+/**
+ * Install a local source directory in developer mode (EXT-06).
+ *
+ * @param options - the directory, the store, the operator allow-gate, and the
+ *   same preview/dependency/provenance options the archive path takes.
+ * @returns the installed (INACTIVE) extension.
+ * @throws ManagementError for every rejection path.
+ */
+export async function stagedInstallFromDirectory(options) {
+    if (!options.allowSourceDirectories) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', 'source-directory installs are not allowed by the operator configuration', 'Enable the developer-mode source-directory source deliberately, or pack the directory into an archive.');
+    }
+    const source = resolve(options.sourceDir);
+    if (!existsSync(source)) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', `the source directory ${source} does not exist`, 'Point at an existing checkout.');
+    }
+    const chainRefusal = ancestorRefusal(source);
+    if (chainRefusal !== undefined) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', chainRefusal, 'Use a path free of junctions and symlinks.');
+    }
+    const storeDir = resolve(options.storeDir);
+    const staging = join(storeDir, '.staging');
+    const attempt = join(staging, `source-${process.pid}-${Date.now().toString(36)}`);
+    mkdirSync(attempt, { recursive: true });
+    try {
+        copyTree(source, attempt, { files: 0, bytes: 0 });
+        const discovery = discoverExtension(attempt);
+        // Install-time lifecycle scripts are refused, never run (EXT-10).
+        refuseInstallScripts(attempt, discovery.packageName, discovery.packageVersion);
+        let lockedDependencies = [];
+        let declared = 0;
+        try {
+            declared = Object.keys(JSON.parse(readFileSync(join(attempt, 'package.json'), 'utf8')).dependencies ?? {}).length;
+        }
+        catch {
+            // Discovery already read package.json.
+        }
+        if (declared > 0) {
+            if (options.dependencies === undefined) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `${discovery.packageName} declares ${declared} runtime dependenc${declared === 1 ? 'y' : 'ies'} but no dependency-graph installer was provided`, 'Provide the operator-configured registry resolver, or bundle the dependencies.');
+            }
+            lockedDependencies = await installDependencyGraph(attempt, options.dependencies);
+        }
+        if (options.preview !== undefined) {
+            const manifest = discovery.manifest;
+            await options.preview({
+                extensionId: discovery.packageName,
+                version: discovery.packageVersion,
+                permissions: manifest.permissions,
+                models: manifest.models.map(model => ({
+                    id: model.id,
+                    assetSet: model.assetSet,
+                    platforms: model.platforms.map(platform => `${platform.os}-${platform.arch}${platform.accelerator === undefined ? '' : `-${platform.accelerator}`}`),
+                })),
+                licenses: (manifest.licenses ?? []).map(layer => `${layer.layer}: ${layer.name}`),
+                downloadImplications: 'developer-mode directory source: nothing is downloaded; the checkout was copied and verified',
+                requiresApproval: false,
+            });
+        }
+        const destination = installPathFor(storeDir, discovery.packageName, discovery.packageVersion);
+        if (existsSync(destination)) {
+            throw new ManagementError('UPGRADE_FAILED', 'install', `${discovery.packageName}@${discovery.packageVersion} is already installed`, 'Install a different version, or uninstall the existing one first.');
+        }
+        mkdirSync(join(destination, '..'), { recursive: true });
+        renameSync(attempt, destination);
+        const runtimeLinkDiagnostic = linkRuntimeSdk(destination);
+        if (runtimeLinkDiagnostic.reason === 'sdk-shadowed') {
+            rmSync(destination, { recursive: true, force: true });
+            throw new ManagementError('INVALID_EXTENSION', 'install', runtimeLinkDiagnostic.detail ?? 'the package ships its own copy of the host runtime SDK', 'Remove node_modules/' + RUNTIME_SDK_NAME + ' from the checkout.');
+        }
+        const contentDigest = digestInstalledContent(destination);
+        writeFileSync(join(destination, '.tool-mode-install.json'), `${JSON.stringify({
+            extensionId: discovery.packageName,
+            version: discovery.packageVersion,
+            archiveDigest: contentDigest, // a directory has no archive; the content digest is the identity
+            ...runtimeLinkDiagnostic === undefined ? {} : { runtimeLink: runtimeLinkDiagnostic },
+            source: { kind: 'local-directory', requested: source },
+            ...lockedDependencies.length === 0 ? {} : { dependencies: lockedDependencies },
+            ...options.provenance === undefined ? {} : { provenance: options.provenance },
+            installedAt: new Date().toISOString(),
+        }, null, 2)}\n`);
+        if (options.record !== false) {
+            const store = new ExtensionStore(storeDir);
+            store.recordInstall({
+                extensionId: discovery.packageName,
+                version: discovery.packageVersion,
+                installPath: destination,
+                archiveDigest: contentDigest,
+                ...runtimeLinkDiagnostic === undefined ? {} : { runtimeLink: runtimeLinkDiagnostic },
+                contentDigest,
+                source: { kind: 'local-directory', requested: source },
+                ...lockedDependencies.length === 0 ? {} : { dependencies: lockedDependencies },
+                ...options.provenance === undefined ? {} : { provenance: options.provenance },
+                installedAt: new Date().toISOString(),
+            });
+        }
+        return {
+            extensionId: discovery.packageName,
+            version: discovery.packageVersion,
+            installPath: destination,
+            activation: 'inactive',
+            discovery,
+            archiveDigest: contentDigest,
+            ...runtimeLinkDiagnostic === undefined ? {} : { runtimeLink: runtimeLinkDiagnostic },
+        };
+    }
+    finally {
+        rmSync(attempt, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=source-directory.js.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/staged.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Staged installation (EXT-07, EXT-08).
+ *
+ * The ordering is the security property. A package is fetched into quarantine,
+ * verified, inspected as DATA, validated, and only then promoted into the store —
+ * and promotion is not activation. Nothing in this module imports extension code,
+ * runs inference, warms a model, or publishes a tool (EXT-07).
+ *
+ * The fetch and extract steps are INJECTED rather than implemented here, for two
+ * reasons: the SDK must stay free of a network stack and an archive library, and
+ * a test must be able to drive every rejection path without a real download or a
+ * real filesystem. The host supplies the real implementations.
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/staged
+ */
+import { type ExtensionDiscovery } from './../discovery.ts';
+import { type InstallDependencyGraph } from './dependencies.ts';
+import { type ArchiveEntry, type ArchiveLimits } from './archive.ts';
+/** How an archive was obtained. */
+export interface InstallSource {
+    /** Where the archive came from, for the receipt. */
+    readonly kind: 'registry' | 'url' | 'local';
+    /** The requested source, recorded verbatim for the audit trail. */
+    readonly requested: string;
+}
+/** What a host must supply to install: bytes in, files out. */
+export interface ArchiveSource {
+    /**
+     * Fetch the archive, bounded.
+     *
+     * The implementation MUST enforce the byte and time limits it is given: the
+     * installer cannot bound a stream it never sees.
+     * @param source - what to fetch.
+     * @param limits - the byte and time bounds.
+     * @returns the archive bytes.
+     */
+    fetch(source: InstallSource, limits: {
+        readonly maxBytes: number;
+        readonly timeoutMs: number;
+    }): Promise<Uint8Array>;
+    /**
+     * List an archive's entries WITHOUT extracting them.
+     * @param bytes - the archive bytes.
+     * @returns the entry list.
+     */
+    list(bytes: Uint8Array): ArchiveEntry[];
+    /**
+     * Extract a validated archive into a directory.
+     *
+     * Only called after {@link validateArchiveEntries} has accepted the entry list,
+     * so an implementation may assume every path is package-relative and link-free.
+     * @param bytes - the archive bytes.
+     * @param destination - the directory to extract into.
+     * @param root - the package root prefix to strip, from `findPackageRoot`.
+     */
+    extract(bytes: Uint8Array, destination: string, root: string): void;
+}
+/** Bounds for one installation attempt. */
+export interface InstallLimits {
+    /** Maximum archive bytes to fetch. */
+    readonly maxArchiveBytes: number;
+    /** Fetch timeout in milliseconds. */
+    readonly fetchTimeoutMs: number;
+    /** Entry-list bounds. */
+    readonly archive: ArchiveLimits;
+}
+/** Conservative install limits. */
+export declare const DEFAULT_INSTALL_LIMITS: InstallLimits;
+/** The result of a successful stage-then-promote installation. */
+export interface StagedInstallResult {
+    /** Extension identity from the validated manifest. */
+    readonly extensionId: string;
+    /** Package version from the validated manifest. */
+    readonly version: string;
+    /** Absolute path of the immutable installation directory. */
+    readonly installPath: string;
+    /**
+     * Always `'inactive'`. Installation is not activation (EXT-07); the field is
+     * returned explicitly so a caller cannot mistake a successful install for a
+     * usable tool.
+     */
+    readonly activation: 'inactive';
+    /** What was discovered, without any of it having been executed. */
+    readonly discovery: ExtensionDiscovery;
+    /** The verified archive digest, for the receipt (EXT-12). */
+    readonly archiveDigest: string;
+}
+/**
+ * The EXT-08 operator approval PREVIEW, produced before materialization.
+ *
+ * The caller inspects the permissions/licences/models/download implications
+ * and may refuse (throw) to abort the install while nothing is promoted.
+ */
+export interface InstallPreview {
+    readonly extensionId: string;
+    readonly version: string;
+    readonly permissions: ExtensionDiscovery['manifest']['permissions'];
+    /** Declared model asset sets with their platform descriptors. */
+    readonly models: readonly {
+        readonly id: string;
+        readonly assetSet: string;
+        readonly platforms: readonly string[];
+    }[];
+    /** The declared licence layers, as `layer: name` strings. */
+    readonly licenses: readonly string[];
+    /** What the install implies for downloads and preparation consent. */
+    readonly downloadImplications: string;
+    /** Whether this install warrants an explicit operator approval. */
+    readonly requiresApproval: boolean;
+}
+/**
+ * Provenance fields recorded AS DATA, NEVER AS TRUST (EXT-12): where the
+ * registry reported integrity/provenance flags, they travel with the install
+ * record for audit; verification is always against the operator-supplied
+ * digest, never against these fields alone.
+ */
+export interface InstallProvenance {
+    /** The registry-recorded integrity string, verbatim. */
+    readonly registryIntegrity?: string;
+    /** Whether the registry reported a build-provenance attestation. */
+    readonly provenance?: boolean;
+    /** Reported attestation references, verbatim. */
+    readonly attestations?: readonly string[];
+    /** Reported signature references, verbatim. */
+    readonly signatures?: readonly string[];
+}
+/**
+ * Install an extension into an operator-owned store, staged (EXT-08).
+ *
+ * Steps, in order: fetch into quarantine → verify integrity → list entries →
+ * validate the entry list → extract → discover → validate compatibility →
+ * promote atomically → record the installation. A failure at any step removes the
+ * quarantine, so a partial install never becomes visible.
+ *
+ * The store is RECORDED rather than merely written to: an installation that is not
+ * in the lock document cannot be activated later, because nothing would know what
+ * bytes were approved.
+ *
+ * @param options - the source, the store, the injected archive source, and limits.
+ * @returns the installed (but inactive) extension.
+ * @throws ManagementError for every rejection path.
+ */
+export declare function stagedInstall(options: {
+    readonly source: InstallSource;
+    /** Absolute path of the operator-owned extension store. */
+    readonly storeDir: string;
+    /** The declared SHA-512 of the archive (EXT-12). */
+    readonly expectedSha512: string;
+    readonly archive: ArchiveSource;
+    readonly limits?: InstallLimits;
+    /** When false, the lock document is not updated. Defaults to true. */
+    readonly record?: boolean;
+    /**
+     * The injected dependency graph installer (EXT-09). When the package
+     * declares runtime dependencies and this is omitted, the install REFUSES
+     * with DEPENDENCY_UNSATISFIED rather than materializing an unresolvable
+     * extension.
+     */
+    readonly dependencies?: InstallDependencyGraph;
+    /** The EXT-08 operator approval preview, called before materialization. */
+    readonly preview?: (preview: InstallPreview) => void | Promise<void>;
+    /** Provenance fields recorded as data, never as trust (EXT-12). */
+    readonly provenance?: InstallProvenance;
+}): Promise<StagedInstallResult>;
+/**
+ * The immutable installation directory for one extension version (EXT-33).
+ *
+ * The identity is VALIDATED rather than merely escaped. Escaping would turn
+ * `../../etc` into a harmless-looking directory name and silently install
+ * something under a package name that no registry would accept; refusing says
+ * what is actually wrong.
+ * @param storeDir - the operator's store root.
+ * @param extensionId - the validated extension identity.
+ * @param version - the validated version.
+ * @returns the absolute installation path.
+ * @throws ManagementError when the identity or version is not a legal one.
+ */
+export declare function installPathFor(storeDir: string, extensionId: string, version: string): string;
+//# sourceMappingURL=staged.d.ts.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/staged.d.ts.map

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