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

package/lib/extension-dependencies.js

@@ -0,0 +1,369 @@
+/**
+ * First-party dependency graphs for developer-mode extension installs (EXT-09).
+ *
+ * Installing a first-party package from its checkout must satisfy the SAME
+ * discipline the SDK applies to a registry install: every declared runtime
+ * dependency is resolved to an exact version, verified by content, and
+ * materialized INSIDE the extension's own immutable installation directory. The
+ * SDK owns that discipline (`installDependencyGraph`); this module supplies the
+ * host half it deliberately leaves injected:
+ *
+ * - the RESOLVER: the exact version of a declared dependency is the one already
+ *   installed in the host's own tree, found by walking `node_modules` upward from
+ *   the source checkout exactly the way Node would. No registry request is made,
+ *   no version is guessed, and a dependency that is not installed refuses the
+ *   install instead of being skipped.
+ * - the ARCHIVE: the resolved package directory is turned into a deterministic
+ *   zip whose SHA-512 is the integrity the SDK verifies before extraction. The
+ *   archive is an ordinary package archive — `node_modules` is excluded because
+ *   the SDK resolves the transitive graph itself, and the package's declared
+ *   install-time scripts are left in place so the SDK's own refusal (EXT-10)
+ *   decides whether the dependency is admissible.
+ *
+ * Two properties matter for truthfulness:
+ *
+ * - **The host's node_modules is READ, never written.** The only write target is
+ *   the SDK's staging directory, which becomes the extension's private
+ *   `node_modules`; the resolver asserts this by construction (it has no write
+ *   path outside the archive bytes).
+ * - **A declaration is never silently dropped.** Every name the extension
+ *   declares is either materialized or the whole install fails with a named
+ *   `DEPENDENCY_UNSATISFIED` reason.
+ *
+ * INTEGRITY NOTE. The SDK's dependency lock records the SHA-512 of the archive
+ * bytes it verified (`verifyIntegrity`), which is what this module computes. The
+ * directory's own identity is additionally checked with the SDK's
+ * `digestInstalledContent` before and after the archive is built, so a checkout
+ * that changes while it is being archived refuses rather than shipping bytes that
+ * no longer match what was resolved.
+ *
+ * @module @try-works/dsh-model-as-tool/extension-dependencies
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import AdmZip from 'adm-zip';
+import { createZipArchiveSource, DEFAULT_ARCHIVE_LIMITS, digestInstalledContent, ManagementError, refuseInstallScripts, } from '@try-works/tool-mode-extension-sdk';
+/** A package identity: one optional scope segment, then one name segment. */
+const PACKAGE_ID = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i;
+/**
+ * The dependency archive byte cap.
+ *
+ * The SDK's `installDependencyGraph` calls `fetch` with a 256 MiB bound and
+ * requires the source to enforce it, so this module refuses an archive it could
+ * not truthfully hand over under that contract.
+ */
+export const MAX_DEPENDENCY_ARCHIVE_BYTES = 256 * 1024 * 1024;
+/**
+ * Refuse an identity that cannot safely become a path component.
+ * @param name - the declared dependency name.
+ * @throws ManagementError `DEPENDENCY_UNSATISFIED` for an unusable name.
+ */
+function assertUsableName(name) {
+    if (!PACKAGE_ID.test(name)) {
+        throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `${JSON.stringify(name)} is not a package name; a dependency declaration must be a name like @scope/name`, 'Correct the dependency name in the extension package.json.');
+    }
+}
+/** Read one installed package's identity, or undefined when it is not a package. */
+function readInstalledPackage(directory, expectedName) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    // SAFETY: the value came from JSON.parse and the object guard above; every field
+    // is re-checked (name equality, string version) before it reaches the caller, so
+    // an unexpected shape is treated as "not this package" rather than trusted.
+    const recorded = parsed;
+    const name = recorded.name;
+    const version = recorded.version;
+    if (name !== expectedName)
+        return undefined;
+    if (typeof version !== 'string' || version.length === 0)
+        return undefined;
+    return { name: expectedName, version, directory };
+}
+/**
+ * Look for a package in the `node_modules` directory of a starting point and every
+ * ancestor, exactly the order Node's own resolver applies.
+ * @param start - a directory inside the requesting tree.
+ * @param name - the dependency name.
+ * @returns the installed package, or undefined when no ancestor holds it.
+ */
+function walkNodeModules(start, name) {
+    let current = resolve(start);
+    for (let depth = 0; depth < 64; depth += 1) {
+        const candidate = join(current, 'node_modules', ...name.split('/'));
+        if (existsSync(join(candidate, 'package.json'))) {
+            const found = readInstalledPackage(candidate, name);
+            if (found !== undefined)
+                return found;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}
+/** The host's own module directory: the fallback tree for host-installed dependencies. */
+function hostModuleDirectory() {
+    return dirname(fileURLToPath(import.meta.url));
+}
+/**
+ * Resolve one declared dependency from the host's installed tree.
+ *
+ * The source checkout's own ancestor chain is searched first (the tree whose
+ * `package.json` declared the dependency), then the host's own module chain, then
+ * any explicitly configured roots. The first installed package whose own
+ * `package.json` name matches wins; nothing is downloaded and no version is
+ * inferred.
+ * @param search - where to look.
+ * @param name - the declared dependency name.
+ * @param range - the declared spec, used only in the refusal message.
+ * @returns the installed dependency.
+ * @throws ManagementError `DEPENDENCY_UNSATISFIED` when it is not installed.
+ */
+export function resolveFirstPartyDependency(search, name, range) {
+    assertUsableName(name);
+    const origins = [resolve(search.sourcePackageDir), hostModuleDirectory()];
+    for (const origin of origins) {
+        const found = walkNodeModules(origin, name);
+        if (found !== undefined)
+            return found;
+    }
+    for (const root of search.extraSearchRoots ?? []) {
+        const candidate = join(resolve(root), 'node_modules', ...name.split('/'));
+        if (existsSync(join(candidate, 'package.json'))) {
+            const found = readInstalledPackage(candidate, name);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `${name} (declared as ${JSON.stringify(range)}) is not installed anywhere in the host's own dependency tree, `
+        + 'so it cannot be materialized into the extension', 'Install the dependency for the host first (or bundle it with the extension); the installer never downloads '
+        + 'dependencies for a source-directory install and never silently drops a declared one.');
+}
+/**
+ * Collect a package directory's files as archive entries.
+ *
+ * `node_modules` is skipped (the SDK resolves the transitive graph through this
+ * same resolver), and any symbolic link or junction inside the tree is REFUSED
+ * rather than followed: a link is how a package reaches bytes outside the content
+ * that was resolved.
+ * @param root - the package directory.
+ * @param limits - the byte bounds.
+ * @returns the selected files, in sorted walk order.
+ */
+function collectPackageFiles(root, limits) {
+    const files = [];
+    let totalBytes = 0;
+    const walk = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+            const absolute = join(current, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the installed dependency contains a symbolic link at ${absolute}; a link makes the archived content differ from the content that was resolved`, 'Repair the installed dependency so the tree contains plain files, then retry.');
+            }
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules')
+                    continue;
+                walk(absolute);
+                continue;
+            }
+            if (!entry.isFile()) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the installed dependency contains ${absolute}, which is neither a file nor a directory`, 'Repair the installed dependency, then retry.');
+            }
+            const size = lstatSync(absolute).size;
+            if (size > limits.maxEntryBytes) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the dependency file ${absolute} is ${size} bytes, over the ${limits.maxEntryBytes}-byte per-file bound`, 'Use a dependency whose individual files fit the archive bounds, or install it outside the extension.');
+            }
+            totalBytes += size;
+            if (totalBytes > limits.maxSourceBytes) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the dependency tree at ${root} is over the ${limits.maxSourceBytes}-byte archive bound`, 'Use a dependency whose installed tree fits the bounds, or install it outside the extension.');
+            }
+            files.push({ relative: relativePath(root, absolute), absolute, size });
+        }
+    };
+    walk(root);
+    if (files.length === 0) {
+        throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the installed dependency at ${root} contains no files`, 'Repair the installed dependency, then retry.');
+    }
+    return files;
+}
+/** A path relative to the package root, using `/` separators for the archive. */
+function relativePath(root, absolute) {
+    return relative(resolve(root), absolute).split('\\').join('/');
+}
+/** Whether a directory is the root or lives underneath it. */
+function isUnder(root, candidate) {
+    const rootPath = resolve(root);
+    const candidatePath = resolve(candidate);
+    if (candidatePath === rootPath)
+        return true;
+    const relativePathFromRoot = relative(rootPath, candidatePath);
+    return relativePathFromRoot.length > 0 && !relativePathFromRoot.startsWith('..') && !isAbsolute(relativePathFromRoot);
+}
+/**
+ * Build a deterministic zip of one installed dependency directory.
+ *
+ * The result is the archive the SDK's dependency graph fetches and verifies. Its
+ * SHA-512 is the integrity handed to the graph; the directory's own
+ * `digestInstalledContent` is checked before and after the build so a concurrent
+ * change refuses.
+ * @param dependency - the resolved installed dependency.
+ * @param limits - the byte bounds.
+ * @returns the archive bytes, their integrity, and the directory digest.
+ * @throws ManagementError `DEPENDENCY_UNSATISFIED` for any refusal.
+ */
+export function buildDependencyArchive(dependency, limits) {
+    const files = collectPackageFiles(dependency.directory, limits);
+    // The same content-digest discipline the SDK applies to a directory install:
+    // the tree's identity is checked around the build, so the archive cannot be
+    // assembled from a tree that changed while it was being read.
+    let before;
+    try {
+        before = digestInstalledContent(dependency.directory);
+    }
+    catch (error) {
+        throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the installed dependency ${dependency.name}@${dependency.version} could not be digested: ${error instanceof Error ? error.message : String(error)}`, 'Repair the installed dependency so every file is readable, then retry.');
+    }
+    const zip = new AdmZip();
+    for (const file of files)
+        zip.addFile(file.relative, readFileSync(file.absolute));
+    const bytes = new Uint8Array(zip.toBuffer());
+    if (bytes.byteLength > limits.maxArchiveBytes) {
+        throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the dependency ${dependency.name}@${dependency.version} archives to ${bytes.byteLength} bytes, over the ${limits.maxArchiveBytes}-byte dependency bound`, 'Use a dependency whose archive fits the installer bound, or install it outside the extension.');
+    }
+    const after = digestInstalledContent(dependency.directory);
+    if (before !== after) {
+        throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the installed dependency ${dependency.name}@${dependency.version} changed while it was being archived`, 'Make sure nothing is installing into the host tree, then retry.');
+    }
+    return {
+        bytes,
+        integrity: createHash('sha512').update(bytes).digest('hex'),
+        contentDigest: after,
+    };
+}
+/**
+ * Decide how this host supplies one dependency, applying the operator gate.
+ *
+ * With the preinstalled gate on, the resolved directory is returned as-is (the SDK
+ * copies it and records provenance; scripts are not run and are NOT stripped).
+ * With the gate off, the bytes arm applies: the SDK's EXT-10 refusal is consulted
+ * BEFORE any archive is built, so a script-declaring dependency refuses cheaply
+ * with the SDK's exact named error, then the archive is built and its SHA-512 is
+ * returned as the integrity the SDK will verify.
+ * @param options - the search tree and gate.
+ * @param limits - the archive bounds used by the bytes arm.
+ * @param name - the declared dependency name.
+ * @param range - the declared dependency spec, for refusals.
+ * @returns the supply decision.
+ * @throws ManagementError `DEPENDENCY_UNSATISFIED` for every refusal.
+ */
+function resolveDependency(options, limits, name, range) {
+    const dependency = resolveFirstPartyDependency(options, name, range);
+    if (options.allowPreinstalled === true) {
+        const root = options.preinstalledRoot;
+        if (root === undefined || !isUnder(root, dependency.directory)) {
+            throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `${dependency.name}@${dependency.version} is installed at ${dependency.directory}, outside the operator-configured preinstalled root ${root ?? '(none configured)'}; preinstalled content may only be copied from inside that root`, 'Configure the preinstalled-dependency root so it contains the host tree this dependency was installed into.');
+        }
+        return { kind: 'preinstalled', dependency, provenance: 'preinstalled' };
+    }
+    // The SDK's own EXT-10 gate runs before any bytes are built: a dependency that
+    // declares an install-time script refuses here with the SDK's exact named error
+    // instead of after a full archive/extract cycle. The SDK checks again after
+    // extraction; this copy is the cheap, identical refusal.
+    refuseInstallScripts(dependency.directory, dependency.name, dependency.version);
+    const built = buildDependencyArchive(dependency, limits);
+    return { kind: 'registry-bytes', dependency, integrity: built.integrity, bytes: built.bytes };
+}
+/**
+ * Create the first-party dependency graph supplied to the SDK's directory installer.
+ *
+ * Resolution and archiving happen lazily, one dependency at a time: `resolve`
+ * builds the exact bytes the SDK will verify and `fetch` hands back those same
+ * bytes, so the integrity the lock records is the integrity of the served archive
+ * rather than a value guessed from metadata. Only the most recently built archive
+ * is retained, which matches the SDK's resolve-then-fetch sequence and bounds
+ * memory to one dependency.
+ *
+ * The preinstalled-content gate is OPT-IN and OFF by default, matching the SDK:
+ * without it every dependency is served as verified bytes and EXT-10 applies. With
+ * it, the SDK requires `preinstalledRoot`, copies the resolved directory into the
+ * extension's own `node_modules`, and records `provenance: 'preinstalled'`.
+ * @param options - the search tree, bounds, gate and forwarded graph limits.
+ * @returns the install-dependency graph plus its resolver and archive halves.
+ * @throws ManagementError `DEPENDENCY_UNSATISFIED` when the gate has no root.
+ */
+export function createFirstPartyDependencyGraph(options) {
+    const limits = {
+        maxSourceBytes: options.maxSourceBytes ?? DEFAULT_ARCHIVE_LIMITS.maxTotalBytes,
+        maxEntryBytes: options.maxEntryBytes ?? DEFAULT_ARCHIVE_LIMITS.maxEntryBytes,
+        maxArchiveBytes: options.maxArchiveBytes ?? MAX_DEPENDENCY_ARCHIVE_BYTES,
+    };
+    let preinstalledGate;
+    if (options.allowPreinstalled === true) {
+        const root = options.preinstalledRoot;
+        if (root === undefined || root.trim().length === 0) {
+            throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', 'the preinstalled-dependency gate is enabled but no operator-configured preinstalled root was supplied', 'Configure the root directory that contains the host dependency tree, or leave the gate off.');
+        }
+        preinstalledGate = { allowPreinstalled: true, preinstalledRoot: resolve(root) };
+    }
+    /** The archive built by the most recent resolve, keyed by name@version. */
+    let latest;
+    const keyOf = (name, version) => `${name}@${version}`;
+    const resolver = {
+        async resolve(name, range) {
+            const supply = resolveDependency(options, limits, name, range);
+            const key = keyOf(supply.dependency.name, supply.dependency.version);
+            if (supply.kind === 'preinstalled') {
+                return {
+                    name: supply.dependency.name,
+                    version: supply.dependency.version,
+                    dir: supply.dependency.directory,
+                    provenance: 'preinstalled',
+                };
+            }
+            latest = { key, bytes: supply.bytes };
+            return {
+                name: supply.dependency.name,
+                version: supply.dependency.version,
+                tarball: { kind: 'local', requested: key },
+                integrity: supply.integrity,
+            };
+        },
+    };
+    const archive = createZipArchiveSource(async (source) => {
+        if (latest === undefined || latest.key !== source.requested) {
+            throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the dependency archive ${source.requested} was not built by the resolver, so it cannot be served`, 'Retry the install; the graph builds each archive immediately before the SDK fetches it.');
+        }
+        if (latest.bytes.byteLength > MAX_DEPENDENCY_ARCHIVE_BYTES) {
+            throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `the dependency archive ${source.requested} is ${latest.bytes.byteLength} bytes, over the ${MAX_DEPENDENCY_ARCHIVE_BYTES}-byte fetch bound`, 'Use a dependency whose archive fits the installer bound.');
+        }
+        return latest.bytes;
+    });
+    /** The optional graph fields, added only when configured (no empty-object spreads). */
+    const optionalGraphFields = {};
+    if (preinstalledGate !== undefined) {
+        optionalGraphFields.allowPreinstalled = preinstalledGate.allowPreinstalled;
+        optionalGraphFields.preinstalledRoot = preinstalledGate.preinstalledRoot;
+    }
+    if (options.maxDepth !== undefined)
+        optionalGraphFields.maxDepth = options.maxDepth;
+    if (options.maxPackages !== undefined)
+        optionalGraphFields.maxPackages = options.maxPackages;
+    const graph = {
+        resolver,
+        archive,
+        ...optionalGraphFields,
+    };
+    return { graph, resolver, archive };
+}
+/** Re-export for callers that want the size bound wording. */
+export { DEFAULT_ARCHIVE_LIMITS };
+//# sourceMappingURL=extension-dependencies.js.map

package/lib/extension-dispatch.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Provider-backed dispatch for extension-declared tools (EXT-19, EXT-21, EXT-22, ARCH-05).
+ *
+ * The TMX runtime API has **no tool-invocation surface**. `ExtensionInstanceV1` exposes
+ * exactly `createProvider` and `dispose` — nothing else. So an extension's tool is not
+ * something the host calls directly; the tool is a caller-facing NAME whose contract is
+ * bound to an IMPLEMENTATION, and the implementation is a model PROVIDER.
+ *
+ *     manifest.tools[]          -> the caller-facing name and its contract
+ *     manifest.implementations[] -> which contract, served by which model
+ *     instance.createProvider() -> the thing that actually runs
+ *
+ * That chain is what this module walks. An earlier version of the host registrar
+ * registered a tool whose `execute` simply REFUSED, which was honest about there being no
+ * implementation bound but left the bridge functionally incomplete: the name appeared in
+ * the registry and could never be called.
+ *
+ * The context is INJECTED so the chain is testable without a real extension on disk.
+ *
+ * @module @try-works/dsh-model-as-tool/extension-dispatch
+ */
+import type { PreparedAssetMap } from './prepared-assets.ts';
+/** What a manifest declares about one tool. */
+export interface DeclaredTool {
+    readonly name: string;
+    readonly contractId: string;
+    readonly contractVersion: string;
+}
+/** What a manifest declares about one implementation. */
+export interface DeclaredImplementation {
+    readonly id: string;
+    readonly contractId: string;
+    readonly contractVersion: string;
+    /** The model that serves the contract. */
+    readonly modelId: string;
+}
+/** The parts of a manifest this module needs. */
+export interface DispatchManifest {
+    readonly tools: readonly DeclaredTool[];
+    readonly implementations: readonly DeclaredImplementation[];
+}
+/** A provider, narrowed to what dispatch needs. */
+export interface DispatchProvider {
+    load(request: {
+        readonly assets: unknown;
+        readonly signal: AbortSignal;
+        /** The manifest model id; the managed worker's load keys by it. */
+        readonly modelId?: string;
+    }): Promise<void>;
+    invoke(request: {
+        readonly implementationId: string;
+        readonly input: Readonly<Record<string, unknown>>;
+        readonly context: unknown;
+    }): Promise<Record<string, unknown>>;
+}
+/** What dispatch needs from the host to reach an extension. */
+export interface DispatchEnvironment {
+    /** The manifest of the activated extension that declared the tool. */
+    getManifest(): DispatchManifest;
+    /** Create (or return a cached) provider for a model deployment. */
+    providerFor(modelId: string): Promise<DispatchProvider>;
+    /** Build the invocation context, which carries host-issued identity. */
+    contextFor(implementationId: string, signal: AbortSignal): unknown;
+    /**
+     * The host's verified prepared-asset map for THIS extension, or undefined
+     * when nothing was prepared (the load then receives the EMPTY map — an
+     * extension needing assets refuses by name inside its own load, which is the
+     * honest MOD-02 behavior rather than an invented verification). Closes over
+     * the extension the environment was built for.
+     */
+    assetsFor?(): PreparedAssetMap | undefined;
+}
+/** Why a tool could not be dispatched. */
+export interface DispatchFailure {
+    readonly code: 'not-declared' | 'no-implementation' | 'unsupported';
+    readonly message: string;
+    readonly remedy: string;
+}
+/**
+ * Resolve the implementation chain for a declared tool.
+ *
+ * @param manifest - the activated extension's manifest.
+ * @param toolName - the caller-facing name.
+ * @returns the tool, its implementation, or why the chain is incomplete.
+ */
+export declare function resolveImplementation(manifest: DispatchManifest, toolName: string): {
+    readonly ok: true;
+    readonly tool: DeclaredTool;
+    readonly implementation: DeclaredImplementation;
+} | {
+    readonly ok: false;
+    readonly failure: DispatchFailure;
+};
+/**
+ * Build an `execute` for one declared tool.
+ *
+ * The provider is created lazily on first call, so ACTIVATION stays lightweight as EXT-19
+ * requires: nothing is loaded until a caller actually invokes the tool.
+ *
+ * @param environment - how to reach the extension.
+ * @param toolName - the caller-facing name.
+ * @returns the execute function, or the failure that prevents one.
+ */
+export declare function createDispatch(environment: DispatchEnvironment, toolName: string): Promise<{
+    readonly ok: true;
+    readonly execute: (args: Record<string, unknown>, signal: AbortSignal) => Promise<Record<string, unknown>>;
+} | {
+    readonly ok: false;
+    readonly failure: DispatchFailure;
+}>;
+/**
+ * Describe a dispatch failure for a caller (EXT-30).
+ * @param failure - the failure.
+ * @returns a readable message naming what to do.
+ */
+export declare function describeDispatchFailure(failure: DispatchFailure): string;
+//# sourceMappingURL=extension-dispatch.d.ts.map

package/lib/extension-dispatch.d.ts.map

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

package/lib/extension-dispatch.js

@@ -0,0 +1,124 @@
+/**
+ * Provider-backed dispatch for extension-declared tools (EXT-19, EXT-21, EXT-22, ARCH-05).
+ *
+ * The TMX runtime API has **no tool-invocation surface**. `ExtensionInstanceV1` exposes
+ * exactly `createProvider` and `dispose` — nothing else. So an extension's tool is not
+ * something the host calls directly; the tool is a caller-facing NAME whose contract is
+ * bound to an IMPLEMENTATION, and the implementation is a model PROVIDER.
+ *
+ *     manifest.tools[]          -> the caller-facing name and its contract
+ *     manifest.implementations[] -> which contract, served by which model
+ *     instance.createProvider() -> the thing that actually runs
+ *
+ * That chain is what this module walks. An earlier version of the host registrar
+ * registered a tool whose `execute` simply REFUSED, which was honest about there being no
+ * implementation bound but left the bridge functionally incomplete: the name appeared in
+ * the registry and could never be called.
+ *
+ * The context is INJECTED so the chain is testable without a real extension on disk.
+ *
+ * @module @try-works/dsh-model-as-tool/extension-dispatch
+ */
+import { assertNoReservedMeta } from '@try-works/tool-mode-extension-sdk';
+/**
+ * Resolve the implementation chain for a declared tool.
+ *
+ * @param manifest - the activated extension's manifest.
+ * @param toolName - the caller-facing name.
+ * @returns the tool, its implementation, or why the chain is incomplete.
+ */
+export function resolveImplementation(manifest, toolName) {
+    const tool = manifest.tools.find(candidate => candidate.name === toolName);
+    if (tool === undefined) {
+        return {
+            ok: false,
+            failure: {
+                code: 'not-declared',
+                message: `${toolName} is not declared by this extension's manifest`,
+                remedy: 'A registered tool must be declared in the manifest it was published from.',
+            },
+        };
+    }
+    const implementation = manifest.implementations.find(candidate => candidate.contractId === tool.contractId && candidate.contractVersion === tool.contractVersion);
+    if (implementation === undefined) {
+        /**
+         * THE HONEST REFUSAL, and the case the earlier stub conflated with every other.
+         *
+         * An extension may DECLARE a tool it does not yet serve — EmbeddingGemma does exactly
+         * this, listing contracts whose ONNX path is not wired. The name is legitimately
+         * registered and legitimately uncallable, and the caller must be told WHICH of those
+         * two situations they are in.
+         */
+        return {
+            ok: false,
+            failure: {
+                code: 'no-implementation',
+                message: `${toolName} declares contract ${tool.contractId}, which no implementation serves`,
+                remedy: 'The extension declares this tool but binds no model to it yet; it is not callable in this build.',
+            },
+        };
+    }
+    return { ok: true, tool, implementation };
+}
+/**
+ * Build an `execute` for one declared tool.
+ *
+ * The provider is created lazily on first call, so ACTIVATION stays lightweight as EXT-19
+ * requires: nothing is loaded until a caller actually invokes the tool.
+ *
+ * @param environment - how to reach the extension.
+ * @param toolName - the caller-facing name.
+ * @returns the execute function, or the failure that prevents one.
+ */
+export async function createDispatch(environment, toolName) {
+    const resolved = resolveImplementation(environment.getManifest(), toolName);
+    if (!resolved.ok)
+        return resolved;
+    const { implementation } = resolved;
+    return {
+        ok: true,
+        async execute(args, signal) {
+            // Resolved per call rather than captured, so a provider that was unloaded — or an
+            // extension that was deactivated and reactivated — is not served from a stale handle.
+            const provider = await environment.providerFor(implementation.modelId);
+            /**
+             * The HOST-VERIFIED prepared-asset map, when a preparation completed.
+             * An absent map means the empty map — the extension's own load refuses a
+             * missing group by name (MOD-02), which is the honest outcome rather than
+             * a host that invents a verification that never happened. The same map
+             * reaches BOTH provider routes here: the in-process module provider and
+             * the managed worker (its load forwards the assets to the child).
+             */
+            const prepared = environment.assetsFor?.();
+            await provider.load({ assets: prepared ?? { get: () => undefined, assetIds: [] }, signal, modelId: implementation.modelId });
+            const value = await provider.invoke({
+                implementationId: implementation.id,
+                input: args,
+                context: environment.contextFor(implementation.id, signal),
+            });
+            /**
+             * THE EXT-17 META RESERVATION IS ENFORCED HERE, AT THE DISPATCH BOUNDARY.
+             *
+             * The reserved root `meta` is HOST-authored provenance; an extension supplying one
+             * is asserting who ran it and under what receipt, which it does not get to do. The
+             * ProviderBridge asserts this on the CATALOG path, but the contribution path
+             * (module and declarative providers alike) went unasserted — so a provider that
+             * smuggled a `meta` key reached callers whenever its declared output schema did not
+             * require the envelope. Asserting at the boundary the two provider routes share
+             * closes the gap for both, and it runs BEFORE any host stamping, so a forged
+             * envelope is refused rather than overwritten.
+             */
+            assertNoReservedMeta(value, implementation.id);
+            return value;
+        },
+    };
+}
+/**
+ * Describe a dispatch failure for a caller (EXT-30).
+ * @param failure - the failure.
+ * @returns a readable message naming what to do.
+ */
+export function describeDispatchFailure(failure) {
+    return `${failure.message}. ${failure.remedy}`;
+}
+//# sourceMappingURL=extension-dispatch.js.map