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

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

@@ -0,0 +1,349 @@
+/**
+ * Installer-owned dependency graphs (EXT-09).
+ *
+ * An extension's runtime dependencies are resolved through the operator's
+ * registry EXACTLY ONCE (ranges lock to exact versions), fetched, verified
+ * against their registry-recorded SHA-512, and materialized into the
+ * extension's OWN immutable installation directory — never the host's
+ * node_modules, never the user's workspace. Lifecycle scripts are refused,
+ * never silently skipped or run: a dependency whose package declares
+ * `prepare`/`preinstall`/`install`/`postinstall` refuses the install with a
+ * named error. The resolved graph (name, exact version, integrity, requested
+ * spec) is recorded in the install record (EXT-12).
+ *
+ * The registry half is INJECTED, like the archive source: the SDK owns the
+ * graph discipline, the host supplies the configured registry and the tarball
+ * transport. An extension's runtime can only import what this installer
+ * materialized — undeclared resolution attempts fail at module load, because
+ * the runtime SDK link is the only bridge into the host tree.
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/dependencies
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { ManagementError } from "./../errors.js";
+import { verifyIntegrity } from "./archive.js";
+/** The defaults for one preinstalled-content copy. */
+const DEFAULT_PREINSTALLED_BYTES = 512 * 1024 * 1024;
+const DEFAULT_PREINSTALLED_FILES = 10_000;
+/** The install-time lifecycle scripts whose presence is a refusal, never a skip. */
+const REFUSED_SCRIPTS = ['prepare', 'preinstall', 'install', 'postinstall'];
+/** Packages that are compile-time- or browser-only and never loaded by the Node host. */
+const NON_RUNTIME_PACKAGES = new Set([
+    'onnxruntime-web',
+]);
+/** Read a package.json's runtime dependencies as name→spec pairs. */
+function declaredDependencies(packageDir, field = 'dependencies') {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+    }
+    catch (error) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', `the package.json could not be read: ${error instanceof Error ? error.message : String(error)}`, 'The archive must ship a parseable package.json.');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', 'the package.json is not an object', 'Ship a valid package.json.');
+    }
+    const dependencies = parsed[field];
+    if (dependencies === undefined)
+        return {};
+    if (typeof dependencies !== 'object' || dependencies === null || Array.isArray(dependencies)) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', 'the package.json dependencies field is not a name→version object', 'Declare runtime dependencies as a plain object of exact versions or ranges.');
+    }
+    const result = {};
+    for (const [name, spec] of Object.entries(dependencies)) {
+        /**
+         * `@types/*` packages are compile-time declarations: nothing imports them at
+         * runtime and they ship no executable code. Materializing them made a real
+         * install fail when two dependencies legitimately needed different type
+         * versions (`mediabunny` → 0.1.13, another package → 0.1.19), which npm
+         * resolves by nesting. Drop them from the runtime graph instead.
+         */
+        if (name.startsWith('@types/'))
+            continue;
+        /**
+         * `onnxruntime-web` is the browser backend of the transformers dependency.
+         * The Node host loads `onnxruntime-node`; materializing both made their
+         * `onnxruntime-common` versions conflict even though the web tree is never
+         * imported at runtime.
+         */
+        if (NON_RUNTIME_PACKAGES.has(name))
+            continue;
+        if (typeof spec !== 'string' || spec.length === 0) {
+            throw new ManagementError('INVALID_EXTENSION', 'install', `the dependency ${JSON.stringify(name)} declares a non-string spec`, 'Declare a version string for every runtime dependency.');
+        }
+        result[name] = spec;
+    }
+    return result;
+}
+/** Refuse a dependency whose package declares install-time lifecycle scripts. */
+export function refuseInstallScripts(packageDir, name, version, trustedPrebuilt = []) {
+    if (trustedPrebuilt.includes(`${name}@${version}`))
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+    }
+    catch (error) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', `the dependency ${name}@${version} ships an unparseable package.json: ${error instanceof Error ? error.message : String(error)}`, 'The dependency tarball must ship a parseable package.json.');
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return;
+    const scripts = parsed['scripts'];
+    if (typeof scripts !== 'object' || scripts === null)
+        return;
+    for (const key of REFUSED_SCRIPTS) {
+        if (key in scripts) {
+            throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `${name}@${version} declares a "${key}" lifecycle script; the installer never runs or silently skips install-time scripts (EXT-10)`, 'Publish a version of the dependency that needs no install-time script (prebuilt artifacts only), or pin a different version.');
+        }
+    }
+}
+/** The content digest of one materialized tree (the digestInstalledContent algorithm). */
+function digestContentOf(directory) {
+    const hash = createHash('sha256');
+    const files = [];
+    const walk = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const absolute = join(current, entry.name);
+            if (entry.isDirectory())
+                walk(absolute);
+            else if (entry.isFile())
+                files.push(absolute);
+        }
+    };
+    walk(directory);
+    for (const file of files.sort()) {
+        const name = relative(directory, file).split(sep).join('/');
+        if (name === '.tool-mode-install.json')
+            continue;
+        const bytes = readFileSync(file);
+        hash.update(name);
+        hash.update('\0');
+        hash.update(String(bytes.byteLength));
+        hash.update('\0');
+        hash.update(createHash('sha256').update(bytes).digest());
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+/**
+ * Copy one preinstalled directory tree into the extension's own install dir.
+ *
+ * A COPY, never a link: the operator's host tree stays untouched and the
+ * extension owns its bytes. Reparse points inside the tree are refused (the
+ * same junction defense the archive path gets), and the copy is bounded.
+ */
+function copyPreinstalledTree(source, destination, limits) {
+    mkdirSync(destination, { recursive: true });
+    let files = 0;
+    let bytes = 0;
+    const walk = (from, to) => {
+        for (const entry of readdirSync(from, { withFileTypes: true })) {
+            const fromPath = join(from, entry.name);
+            const toPath = join(to, entry.name);
+            if (entry.isSymbolicLink() || (entry.isFile() === false && entry.isDirectory() === false)) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `${fromPath} is a reparse point; preinstalled content must not smuggle links into the installation`, 'Point at a real directory tree, or resolve the dependency from registry bytes.');
+            }
+            if (entry.isDirectory()) {
+                // The parent directory for this subtree must EXIST before any nested
+                // file is copied into it: copyFileSync does not create parents, and on
+                // Windows a missing parent raises ENOENT on the destination side
+                // (task-88: the live MiniLM install failed copying dist/… before this).
+                mkdirSync(toPath, { recursive: true });
+                walk(fromPath, toPath);
+                continue;
+            }
+            files += 1;
+            bytes += statSync(fromPath).size;
+            if (files > limits.files || bytes > limits.bytes) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the preinstalled content exceeds the copy bounds (${limits.files} files / ${limits.bytes} bytes)`, 'Raise the operator bounds deliberately, or resolve the dependency from registry bytes.');
+            }
+            copyFileSync(fromPath, toPath);
+        }
+    };
+    walk(source, destination);
+}
+/**
+ * Resolve, fetch, verify and materialize one extension's dependency graph.
+ *
+ * Bounded BFS: ranges resolve exactly once, registry tarballs verify against
+ * their registry integrity, scripts are refused on the registry arm, and the
+ * graph is flattened into the extension's own `node_modules` (a private root —
+ * no hoisting into any other tree). Version conflicts within one graph are
+ * REFUSED rather than silently duplicated; the count and depth caps refuse
+ * runaway graphs by name.
+ *
+ * The PREINSTALLED arm is operator-gated: only when `allowPreinstalled` is set
+ * does a resolver-supplied directory get copied (bounded, path-escape-checked
+ * against `preinstalledRoot`, reparse-point-refused) into the extension's own
+ * tree, with the record's provenance stating that the installer ran no
+ * lifecycle script on it.
+ *
+ * @param packageDir - the extracted extension package directory.
+ * @param graph - the injected resolver/archive plus the bounds and the gate.
+ * @returns the locked dependency records, in materialization order.
+ */
+export async function installDependencyGraph(packageDir, graph) {
+    const maxDepth = graph.maxDepth ?? 3;
+    const maxPackages = graph.maxPackages ?? 64;
+    const declared = declaredDependencies(packageDir);
+    if (Object.keys(declared).length === 0)
+        return [];
+    const nodeModules = join(packageDir, 'node_modules');
+    const locked = [];
+    const visited = new Set();
+    const hoisted = new Map(); // name -> exact version already materialized
+    const queue = Object.entries(declared)
+        .map(([name, range]) => ({ name, range, depth: 0, optional: false }));
+    while (queue.length > 0) {
+        const entry = queue.shift();
+        if (visited.has(`${entry.name}@${entry.range}`))
+            continue;
+        visited.add(`${entry.name}@${entry.range}`);
+        if (entry.depth > maxDepth) {
+            // An OPTIONAL child that sits too deep is skipped, not refused: optional
+            // means the package must still work without it (sharp's platform binaries
+            // are optional at every depth). A required child still refuses by name.
+            if (entry.optional)
+                continue;
+            throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the dependency graph exceeds the ${maxDepth}-level depth bound at ${entry.name}`, 'Flatten the dependency tree or raise the operator bound deliberately.');
+        }
+        if (locked.length >= maxPackages && !hoisted.has(entry.name)) {
+            if (entry.optional)
+                continue;
+            throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the dependency graph exceeds the ${maxPackages}-package bound`, 'Reduce the graph or raise the operator bound deliberately.');
+        }
+        let resolvedEntry;
+        try {
+            resolvedEntry = await graph.resolver.resolve(entry.name, entry.range);
+        }
+        catch (error) {
+            // An unresolvable OPTIONAL dependency is recorded as absent by omission and
+            // the install continues; only a REQUIRED dependency refuses the graph.
+            if (entry.optional)
+                continue;
+            throw error;
+        }
+        const existing = hoisted.get(resolvedEntry.name);
+        if (existing !== undefined && existing !== resolvedEntry.version) {
+            throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the dependency graph needs both ${resolvedEntry.name}@${existing} and ${resolvedEntry.name}@${resolvedEntry.version}; `
+                + 'conflicting versions inside one extension are refused rather than silently duplicated', 'Pin the two requesters to one version, or publish a compatible version.');
+        }
+        if (existing !== undefined) {
+            // Already materialized at the same exact version: nothing more to fetch.
+            const transitive = declaredDependencies(join(nodeModules, resolvedEntry.name));
+            for (const [childName, childRange] of Object.entries(transitive)) {
+                if (!visited.has(`${childName}@${childRange}`))
+                    queue.push({ name: childName, range: childRange, depth: entry.depth + 1, optional: false });
+            }
+            for (const [childName, childRange] of Object.entries(declaredDependencies(join(nodeModules, resolvedEntry.name), 'optionalDependencies'))) {
+                if (!visited.has(`${childName}@${childRange}`))
+                    queue.push({ name: childName, range: childRange, depth: entry.depth + 1, optional: true });
+            }
+            continue;
+        }
+        if (resolvedEntry.provenance === 'preinstalled') {
+            // The preinstalled arm: operator-gated, boundary-checked, copied (never
+            // linked), digested from the copied bytes, and recorded truthfully.
+            if (graph.allowPreinstalled !== true) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `${resolvedEntry.name}@${resolvedEntry.version} resolved to preinstalled content, but the preinstalled source is not enabled by the operator (allowPreinstalled)`, 'Enable the preinstalled source deliberately for this install, or resolve the dependency from registry bytes.');
+            }
+            if (graph.preinstalledRoot === undefined) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', 'preinstalled content requires an operator-configured preinstalledRoot so the source boundary can be enforced', 'Set preinstalledRoot to the directory that holds the host-tree packages.');
+            }
+            const root = resolve(graph.preinstalledRoot);
+            const dir = resolve(resolvedEntry.dir);
+            const rel = relative(root, dir);
+            if (rel === '' || rel.startsWith('..') || isAbsolute(rel) || !existsSync(dir)) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the preinstalled directory ${dir} is outside the operator-configured root ${root} (path-escape refused)`, 'Only preinstalled directories inside preinstalledRoot may be copied.');
+            }
+            // Honesty check: the content must BE the package the resolver claims.
+            let dirPackage;
+            try {
+                const parsed = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+                dirPackage = parsed;
+            }
+            catch (error) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the preinstalled content at ${dir} ships an unreadable package.json: ${error instanceof Error ? error.message : String(error)}`, 'Preinstalled content must ship a parseable package.json.');
+            }
+            if (dirPackage.name !== resolvedEntry.name || dirPackage.version !== resolvedEntry.version) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the preinstalled content at ${dir} is ${String(dirPackage.name)}@${String(dirPackage.version)}, not the resolved ${resolvedEntry.name}@${resolvedEntry.version}`, 'Point at the directory that actually holds the resolved package.');
+            }
+            const attempt = join(nodeModules, `.dep-${process.pid}-${Date.now().toString(36)}`);
+            mkdirSync(attempt, { recursive: true });
+            try {
+                // The scripts field is left UNTOUCHED and NO lifecycle script is run:
+                // the content arrived already materialized by a completed host install,
+                // and provenance:'preinstalled' records exactly that.
+                copyPreinstalledTree(dir, attempt, {
+                    files: graph.maxPreinstalledFiles ?? DEFAULT_PREINSTALLED_FILES,
+                    bytes: graph.maxPreinstalledBytes ?? DEFAULT_PREINSTALLED_BYTES,
+                });
+                const digest = digestContentOf(attempt);
+                const destination = join(nodeModules, resolvedEntry.name);
+                mkdirSync(join(destination, '..'), { recursive: true });
+                renameSync(attempt, destination);
+                hoisted.set(resolvedEntry.name, resolvedEntry.version);
+                locked.push({
+                    name: resolvedEntry.name,
+                    version: resolvedEntry.version,
+                    integrity: digest,
+                    resolvedFrom: entry.range,
+                    provenance: 'preinstalled',
+                    preinstalledFrom: resolvedEntry.dir,
+                });
+                const transitive = declaredDependencies(destination);
+                for (const [childName, childRange] of Object.entries(transitive)) {
+                    if (!visited.has(`${childName}@${childRange}`))
+                        queue.push({ name: childName, range: childRange, depth: entry.depth + 1, optional: false });
+                }
+                for (const [childName, childRange] of Object.entries(declaredDependencies(destination, 'optionalDependencies'))) {
+                    if (!visited.has(`${childName}@${childRange}`))
+                        queue.push({ name: childName, range: childRange, depth: entry.depth + 1, optional: true });
+                }
+            }
+            finally {
+                rmSync(attempt, { recursive: true, force: true });
+            }
+            continue;
+        }
+        const bytes = await graph.archive.fetch(resolvedEntry.tarball, {
+            maxBytes: 256 * 1024 * 1024,
+            timeoutMs: 120_000,
+        });
+        const digest = verifyIntegrity(bytes, resolvedEntry.integrity);
+        const attempt = join(nodeModules, `.dep-${process.pid}-${Date.now().toString(36)}`);
+        mkdirSync(attempt, { recursive: true });
+        try {
+            // The archive source strips the package root itself (the same contract
+            // stagedInstall relies on), so the extracted content IS the package.
+            graph.archive.extract(bytes, attempt, '');
+            refuseInstallScripts(attempt, resolvedEntry.name, resolvedEntry.version, graph.trustedPrebuiltDependencies);
+            const destination = join(nodeModules, resolvedEntry.name);
+            mkdirSync(join(destination, '..'), { recursive: true });
+            renameSync(attempt, destination);
+            hoisted.set(resolvedEntry.name, resolvedEntry.version);
+            locked.push({
+                name: resolvedEntry.name,
+                version: resolvedEntry.version,
+                integrity: digest,
+                resolvedFrom: entry.range,
+            });
+            const transitive = declaredDependencies(destination);
+            for (const [childName, childRange] of Object.entries(transitive)) {
+                if (!visited.has(`${childName}@${childRange}`))
+                    queue.push({ name: childName, range: childRange, depth: entry.depth + 1, optional: false });
+            }
+            for (const [childName, childRange] of Object.entries(declaredDependencies(destination, 'optionalDependencies'))) {
+                if (!visited.has(`${childName}@${childRange}`))
+                    queue.push({ name: childName, range: childRange, depth: entry.depth + 1, optional: true });
+            }
+        }
+        finally {
+            rmSync(attempt, { recursive: true, force: true });
+        }
+    }
+    return locked;
+}
+//# sourceMappingURL=dependencies.js.map

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

@@ -0,0 +1,274 @@
+/**
+ * Activation and deactivation (EXT-04, EXT-26, EXT-27, EXT-28).
+ *
+ * The two orderings this module exists to enforce:
+ *
+ * - **Activate commits last.** Contributions are published to a candidate set,
+ *   and the catalog generation advances only once EVERY required contribution has
+ *   been accepted. A half-activated package is worse than an inactive one,
+ *   because tools would appear that nothing can serve.
+ * - **Deactivate persists intent first.** The inactive preference is made durable
+ *   BEFORE anything is withdrawn. If withdrawal then fails or the process dies,
+ *   the durable answer is still "inactive", so a restart cannot resurrect a
+ *   package the operator switched off.
+ *
+ * Rollback is deliberately NARROW: a failed activation withdraws only the handles
+ * it published itself. Touching another extension's contributions would turn one
+ * bad package into an outage of every package.
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/lifecycle
+ */
+import { ExtensionStore } from './store.ts';
+import { summarize, type ExtensionState, type ModelReadiness } from './../state.ts';
+/** One contribution a registrar can publish. */
+export interface Contribution {
+    /** The extension that owns it. */
+    readonly extensionId: string;
+    /** What kind of contribution it is. */
+    readonly kind: 'tool' | 'skill' | 'implementation';
+    /** The caller-facing name for a tool or skill; the local id otherwise. */
+    readonly name: string;
+    /** The contract this contribution implements, for tools and implementations. */
+    readonly contractId?: string;
+}
+/** What can publish and withdraw contributions. Injected, so the SDK stays host-free. */
+export interface ContributionRegistrar {
+    /**
+     * Publish one contribution.
+     * @param contribution - what to publish.
+     * @returns an opaque handle used to withdraw it.
+     */
+    publish(contribution: Contribution): Promise<string> | string;
+    /**
+     * Withdraw a published contribution.
+     * @param handle - the handle returned by {@link ContributionRegistrar.publish}.
+     */
+    withdraw(handle: string): Promise<void> | void;
+}
+/** A diagnostic about an activation that succeeded with caveats. */
+export interface ActivationDiagnostic {
+    /** Stable code, e.g. `needs-preparation`. */
+    readonly code: 'needs-preparation' | 'not-registerable';
+    /** Human-readable detail. */
+    readonly message: string;
+    /** The contribution or deployment the diagnostic concerns. */
+    readonly subject?: string;
+}
+/** Options for an activation attempt. */
+export interface ActivationOptions {
+    /**
+     * Whether a failed attempt records its cause in `activationError`.
+     *
+     * The prepare probe deliberately performs the operator's failed activation to
+     * create a profile row. Its publish refusal is an artifact of the probe host,
+     * not an operator-facing cause, so it must not overwrite the durable reason.
+     */
+    readonly recordFailure?: boolean;
+}
+/** The outcome of an activation. */
+export interface ActivationResult {
+    readonly extensionId: string;
+    readonly version: string;
+    /** The state as observed after the attempt. */
+    readonly state: ExtensionState;
+    /** Caveats that do not block activation (EXT-26). */
+    readonly diagnostics: readonly ActivationDiagnostic[];
+    /** The catalog generation after the attempt; unchanged when it failed. */
+    readonly generation: number;
+}
+/** The outcome of a deactivation. */
+export interface DeactivationResult {
+    readonly extensionId: string;
+    readonly state: ExtensionState;
+    /**
+     * True only when every contribution was withdrawn AND every owned resource
+     * reported stopped. EXT-27 forbids reporting a package as fully stopped while
+     * an uncontrolled worker continues.
+     */
+    readonly fullyStopped: boolean;
+    /** Why it is not fully stopped, when it is not. */
+    readonly cleanupFailure?: string;
+    /**
+     * The onWithdrawal hook's own failure, when it threw or rejected. The hook is
+     * a TEARDOWN observer: its error is surfaced here, never thrown — the
+     * deactivation's state write has already committed and must not be lost to a
+     * disposal callback that failed.
+     */
+    readonly hookFailure?: string;
+    readonly generation: number;
+}
+/**
+ * A teardown observer, invoked exactly once per withdrawn extension.
+ *
+ * `onWithdrawal` runs AFTER the lifecycle has finished withdrawing the
+ * extension's contribution handles and BEFORE the deactivation's final state
+ * write settles. A host uses it to dispose out-of-process resources (managed
+ * workers, native handles) at the one moment where the durable answer is
+ * already "inactive" and the registry surface is gone.
+ */
+export type OnWithdrawal = (extensionId: string) => void | Promise<void>;
+/** Default grace period for a contribution to finish stopping, in milliseconds. */
+export declare const DEFAULT_STOP_GRACE_MS = 5000;
+/**
+ * Whether an extension's readiness should block activation.
+ *
+ * EXT-26 is explicit that a valid package with merely UNPREPARED model assets may
+ * be active with `needs-preparation` diagnostics: the tools exist and can be
+ * described, and preparation happens on first use. A FAILED model is different —
+ * it will not become ready by waiting.
+ * @param readiness - per-deployment readiness.
+ * @returns diagnostics, and whether activation may proceed.
+ */
+export declare function assessReadiness(readiness: Readonly<Record<string, ModelReadiness>>): {
+    readonly proceed: boolean;
+    readonly diagnostics: readonly ActivationDiagnostic[];
+};
+/** One lifecycle operation outcome (EXT-35), emitted apart from invocation receipts. */
+export interface LifecycleAuditEvent {
+    /** What was attempted. */
+    readonly operation: 'install' | 'prepare' | 'activate' | 'deactivate' | 'update' | 'uninstall';
+    /** The extension concerned. */
+    readonly extensionId: string;
+    /** The version, when the operation concerned one. */
+    readonly version: string | null;
+    /** Whether it succeeded. */
+    readonly outcome: 'succeeded' | 'failed';
+    /** The failure reason, when it failed. */
+    readonly reason?: string;
+}
+/** The extension lifecycle for one profile. */
+export declare class ExtensionLifecycle {
+    #private;
+    constructor(options: {
+        readonly store: ExtensionStore;
+        readonly profile: string;
+        readonly registrar: ContributionRegistrar;
+        /** Starting catalog generation; defaults to 1. */
+        readonly generation?: number;
+        /**
+         * A teardown observer for host-managed out-of-process resources, invoked
+         * once per withdrawn extension AFTER handle teardown and BEFORE the final
+         * deactivation state write settles (see {@link OnWithdrawal}).
+         */
+        readonly onWithdrawal?: OnWithdrawal;
+        /**
+         * Protected built-in extension ids from the HOST RELEASE's trusted lock (EXT-03).
+         * Never populated from a package manifest; an extension cannot grant itself this
+         * status. Protected ids refuse uninstall with `BUILTIN_PROTECTED`.
+         */
+        readonly protectedBuiltins?: readonly string[];
+        /**
+         * LIC-04: a strict no-network deployment admits only implementations whose
+         * DECLARED behaviour allows it. Ineligible extensions are refused at activation;
+         * their telemetry is never silently suppressed.
+         */
+        readonly networkPolicy?: 'any' | 'no-network';
+        /**
+         * EXT-35: receive lifecycle operation outcomes, separate from invocation
+         * receipts. The host decides retention/principal; the SDK only reports.
+         */
+        readonly onAudit?: (event: LifecycleAuditEvent) => void;
+    });
+    /** The current catalog generation. */
+    get generation(): number;
+    /** Read the persisted states for this profile. */
+    states(): readonly ExtensionState[];
+    /** Read one extension's persisted state. */
+    stateOf(extensionId: string): ExtensionState | undefined;
+    /**
+     * Activate an installed extension (EXT-26).
+     *
+     * Verifies the installed bytes and locks, checks readiness, publishes every
+     * required contribution, and advances the generation only if all of that
+     * succeeded. On any failure the contributions THIS call published are withdrawn
+     * and the generation is left where it was.
+     * @param extensionId - the extension to activate.
+     * @param version - the installed version to activate.
+     * @param options - failure-recording policy for probe activations.
+     * @returns the activation outcome.
+     * @throws ManagementError when the extension is not installed, its content changed, or a contribution cannot be registered.
+     */
+    activate(extensionId: string, version: string, options?: ActivationOptions): Promise<ActivationResult>;
+    /**
+     * Retry owned deletion left pending by a previous uninstall (EXT-29).
+     *
+     * An uninstall that could not delete its private installation keeps the record and
+     * leaves the installation absent in the profile state. On restart this finds only
+     * those records, deletes exactly the recorded path, and removes the record only
+     * after the deletion succeeds.
+     * @returns the cleaned ids and the failures with reasons.
+     */
+    retryCleanupPending(): Promise<{
+        readonly cleaned: readonly string[];
+        readonly failed: readonly {
+            readonly extensionId: string;
+            readonly reason: string;
+        }[];
+    }>;
+    /**
+     * Deactivate an extension (EXT-27).
+     *
+     * The inactive intent is made durable FIRST, so a failure or crash during
+     * withdrawal cannot resurrect the package on the next start.
+     * @param extensionId - the extension to deactivate.
+     * @returns the deactivation outcome, which reports honestly when it is not fully stopped.
+     */
+    deactivate(extensionId: string): Promise<DeactivationResult>;
+    /**
+     * Enable or disable ONE tool inside an active extension (EXT-04).
+     *
+     * Independent of activation: the package stays active while a single tool is
+     * hidden from callers.
+     *
+     * ASYNC because the toggle also reconciles the PUBLISHED surface: a disabled
+     * tool is withdrawn from the registrar rather than merely remembered as off,
+     * and a re-enabled one is published again. When this instance does not own the
+     * surface — a CLI with no host attached — only the durable choice is recorded,
+     * because it cannot manage a registry another process owns.
+     * @param extensionId - the owning extension.
+     * @param toolName - the tool to toggle.
+     * @param enabled - the new visibility.
+     * @throws ManagementError when the extension or tool is unknown.
+     * @returns the state after the change.
+     */
+    setToolEnabled(extensionId: string, toolName: string, enabled: boolean): Promise<ExtensionState>;
+    /**
+     * Whether a tool may be invoked right now.
+     * @param extensionId - the owning extension.
+     * @param toolName - the tool being invoked.
+     */
+    admits(extensionId: string, toolName: string): boolean;
+    /**
+     * Uninstall an installed extension (EXT-04, EXT-28).
+     * @param extensionId - the extension to remove.
+     * @param options - `deactivate` must be set to remove an active package.
+     * @throws ManagementError `EXTENSION_IN_USE`, `BUILTIN_PROTECTED`, or `EXTENSION_INACTIVE`.
+     */
+    uninstall(extensionId: string, options?: {
+        readonly deactivate?: boolean;
+    }): Promise<void>;
+    /**
+     * Record host-inspected readiness for an extension's declared deployments.
+     *
+     * This is the production writer `#readinessOf` reads: without it, every declared
+     * model stays `needs-preparation` forever and a model-backed package can never
+     * publish a callable tool. Inspection is the host's read-only EXT-18 surface, so
+     * recording it here is how "prepared" becomes a durable fact rather than a guess.
+     *
+     * Only values for deployments the CURRENT manifest declares are kept, matching the
+     * projection `#readinessOf` already applies, and `failed` is recorded so a failed
+     * deployment refuses activation instead of staying silent.
+     *
+     * ASYNC because a readiness CHANGE also moves the surface: a deployment that just
+     * became `failed` must have its tool withdrawn, and one that just became callable
+     * must be published. Recording without reconciling would leave the published
+     * snapshot stale, which is exactly the divergence admission exists to prevent.
+     * @param extensionId - the extension whose deployments were inspected.
+     * @param inspected - readiness keyed by deployment id.
+     * @returns the state after recording.
+     * @throws ManagementError when the extension is not installed.
+     */
+    recordReadiness(extensionId: string, inspected: Readonly<Record<string, ModelReadiness>>): Promise<ExtensionState>;
+}
+export { summarize };
+//# sourceMappingURL=lifecycle.d.ts.map

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

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