@try-works/dsh-model-as-tool 0.0.0-stage → 0.1.0

package/lib/adapters/index.js

@@ -0,0 +1,67 @@
+/**
+ * Adapter registry: the one place that maps a catalog model to the code that
+ * can invoke it.
+ *
+ * Two kinds of adapter exist. A **model adapter** is written by hand for a model
+ * with a real in-process SDK (Tongue, Voz). A **transport adapter** is generic:
+ * it drives any model through the Desert Ant CLI or a user-hosted bridge, using
+ * only the catalog's verb and parameter declarations.
+ *
+ * @module @try-works/dsh-model-as-tool/adapters/index
+ */
+import { createTongueAdapter } from "./tongue.js";
+import { createVozAdapter } from "./voz.js";
+import { createCliTransport, createRemoteTransport, } from "../transport.js";
+/**
+ * Every hand-written adapter this plugin ships, in priority order.
+ *
+ * Each factory returns undefined for the entries it does not serve, so the
+ * lookup is a linear scan rather than a switch, and a model with no adapter yet
+ * simply has no tool.
+ */
+export const ADAPTER_FACTORIES = [
+    createTongueAdapter,
+    createVozAdapter,
+];
+/**
+ * Wrap a command transport as a model adapter.
+ *
+ * The transport already returns the canonical object, so this is a pure
+ * adaptation of shape rather than a second place that knows how to parse a
+ * result.
+ * @param entry - the catalog entry.
+ * @param transport - the CLI or remote transport.
+ * @returns the adapter.
+ */
+function transportAdapter(entry, transport) {
+    return {
+        modelId: entry.id,
+        invoke: ({ args, signal }) => transport.invoke({ entry, args, signal }),
+    };
+}
+/**
+ * Create the adapter for one entry.
+ *
+ * A hand-written adapter always wins for the model it serves: an in-process
+ * call is faster and needs no external service. Everything else falls to the
+ * transport the capability resolver selected.
+ * @param entry - the catalog entry.
+ * @param options - the resolved route plus transport settings.
+ * @param factories - hand-written adapter factories, defaulting to the shipped set.
+ * @returns the adapter, or undefined when no factory or transport serves this model.
+ */
+export function createAdapter(entry, options = { route: 'npm-native' }, factories = ADAPTER_FACTORIES) {
+    for (const factory of factories) {
+        const adapter = factory(entry);
+        if (adapter !== undefined)
+            return adapter;
+    }
+    // No hand-written adapter: the model is reachable only through a transport.
+    if (options.route === 'cli')
+        return transportAdapter(entry, createCliTransport(entry, options));
+    if (options.route === 'remote') {
+        return transportAdapter(entry, createRemoteTransport(entry, options));
+    }
+    return undefined;
+}
+//# sourceMappingURL=index.js.map

package/lib/adapters/tongue.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tongue adapter — on-device language identification for short text.
+ *
+ * Tongue is the one Desert Ant model that runs in plain Node on every platform:
+ * it is pure JavaScript with no WASM or inference runtime, and its 2 MB model
+ * ships inside the npm package. That makes it the reference adapter: the module
+ * is imported on first use, the loaded model is cached for the process, and the
+ * synchronous `detect()` is wrapped in the async tool contract.
+ *
+ * @module @try-works/dsh-model-as-tool/adapters/tongue
+ */
+import type { ModelCatalogEntry } from '../types.ts';
+import { type ModelAdapter } from './types.ts';
+/**
+ * Build the Tongue adapter.
+ *
+ * The model is loaded once and reused, because `Tongue.load()` parses the
+ * bundled 2 MB weight file and detection afterwards is synchronous.
+ * @param entry - the catalog entry this adapter serves.
+ * @returns the adapter, or undefined if the entry is not Tongue.
+ */
+export declare function createTongueAdapter(entry: ModelCatalogEntry): ModelAdapter | undefined;
+//# sourceMappingURL=tongue.d.ts.map

package/lib/adapters/tongue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tongue.d.ts","sourceRoot":"","sources":["../../src/adapters/tongue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AA4BnB;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,SAAS,CAwDtF"}

package/lib/adapters/tongue.js

@@ -0,0 +1,85 @@
+/**
+ * Tongue adapter — on-device language identification for short text.
+ *
+ * Tongue is the one Desert Ant model that runs in plain Node on every platform:
+ * it is pure JavaScript with no WASM or inference runtime, and its 2 MB model
+ * ships inside the npm package. That makes it the reference adapter: the module
+ * is imported on first use, the loaded model is cached for the process, and the
+ * synchronous `detect()` is wrapped in the async tool contract.
+ *
+ * @module @try-works/dsh-model-as-tool/adapters/tongue
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { optionalInteger, requireString, throwIfAborted, } from "./types.js";
+/** Default number of runner-up candidates reported to the model. */
+const DEFAULT_TOP = 3;
+const MAX_TOP = 20;
+/**
+ * Build the Tongue adapter.
+ *
+ * The model is loaded once and reused, because `Tongue.load()` parses the
+ * bundled 2 MB weight file and detection afterwards is synchronous.
+ * @param entry - the catalog entry this adapter serves.
+ * @returns the adapter, or undefined if the entry is not Tongue.
+ */
+export function createTongueAdapter(entry) {
+    if (entry.id !== 'tongue')
+        return undefined;
+    let loaded;
+    const load = async () => {
+        loaded ??= (async () => {
+            try {
+                // A dynamic import keyed off a variable keeps this out of the module
+                // graph until the tool is actually called: the package is an optional
+                // dependency, so a static import would break installs that skip it.
+                const specifier = entry.npmPackage;
+                const module = await import(__rewriteRelativeImportExtension(specifier));
+                return await module.Tongue.load();
+            }
+            catch (error) {
+                // Clear the cache so a transient failure (or a later install) can be
+                // retried by the next call rather than poisoning the tool for the life
+                // of the plugin.
+                loaded = undefined;
+                throw new Error(`Tongue could not be loaded: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        })();
+        return loaded;
+    };
+    return {
+        modelId: entry.id,
+        async invoke({ args, signal }) {
+            throwIfAborted(signal);
+            const text = requireString(args, 'text');
+            const top = optionalInteger(args, 'top', { min: 1, max: MAX_TOP, fallback: DEFAULT_TOP });
+            const tongue = await load();
+            throwIfAborted(signal);
+            const detection = tongue.detect(text);
+            const candidates = (detection.candidates ?? []).slice(0, top);
+            return {
+                language: detection.language,
+                reliability: detection.reliability ?? 'unknown',
+                isTooCloseToCall: detection.isTooCloseToCall ?? false,
+                candidates: candidates.map(candidate => ({
+                    language: candidate.language,
+                    probability: candidate.probability,
+                })),
+            };
+        },
+        async dispose() {
+            if (loaded === undefined)
+                return;
+            const instance = await loaded.catch(() => undefined);
+            instance?.dispose?.();
+            loaded = undefined;
+        },
+    };
+}
+//# sourceMappingURL=tongue.js.map

package/lib/adapters/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The adapter seam: how one catalog model is actually invoked.
+ *
+ * An adapter is responsible for exactly two things — loading its model lazily
+ * and turning validated tool arguments into the canonical JSON value the tool
+ * declares. Everything else (which models exist, whether they may run, what the
+ * model sees) belongs to the catalog, the capability resolver, and the
+ * registrar.
+ *
+ * @module @try-works/dsh-model-as-tool/adapters/types
+ */
+import type { ModelCatalogEntry } from '../types.ts';
+/** A lossless JSON value, the only thing a tool body may return. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** One adapter invocation. */
+export interface AdapterInvocation {
+    /** Validated tool arguments, already constrained by the registered parameter schema. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Caller cancellation, forwarded by the tool body. */
+    readonly signal: AbortSignal;
+}
+/** One model's invocation strategy. */
+export interface ModelAdapter {
+    /** The catalog id this adapter serves. */
+    readonly modelId: string;
+    /**
+     * Run the model once and return the canonical value.
+     *
+     * Every model tool declares an object output schema, so an adapter returns an
+     * object rather than an arbitrary JSON root.
+     * @param invocation - validated arguments and caller cancellation.
+     * @returns the lossless JSON object declared by the tool's output schema.
+     */
+    invoke(invocation: AdapterInvocation): Promise<Record<string, JsonValue>>;
+    /**
+     * Release any process-level model resources.
+     *
+     * Called on plugin dispose. Adapters that cache a loaded model must implement
+     * it; adapters that hold nothing may omit it.
+     */
+    dispose?(): Promise<void>;
+}
+/** Build an adapter for one runnable model, or `undefined` when none exists yet. */
+export type AdapterFactory = (entry: ModelCatalogEntry) => ModelAdapter | undefined;
+/**
+ * Reject an aborted call before doing model work.
+ * @param signal - caller cancellation.
+ * @throws the abort reason when the signal is already aborted.
+ */
+export declare function throwIfAborted(signal: AbortSignal): void;
+/**
+ * Read a required string argument.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @returns the string value.
+ * @throws when the value is absent or not a string.
+ */
+export declare function requireString(args: Readonly<Record<string, unknown>>, key: string): string;
+/**
+ * Read an optional integer argument, clamped to a range.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param options - inclusive bounds and the value to use when absent.
+ * @returns the resolved integer.
+ * @throws when the value is present but not an integer in range.
+ */
+export declare function optionalInteger(args: Readonly<Record<string, unknown>>, key: string, options: {
+    readonly min: number;
+    readonly max: number;
+    readonly fallback: number;
+}): number;
+/**
+ * Read an optional number in a range.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param options - inclusive bounds.
+ * @returns the resolved number, or undefined when absent.
+ * @throws when the value is present but not a finite number in range.
+ */
+export declare function optionalNumber(args: Readonly<Record<string, unknown>>, key: string, options: {
+    readonly min: number;
+    readonly max: number;
+}): number | undefined;
+/**
+ * Read a required boolean argument.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param fallback - value used when the argument is absent.
+ * @returns the resolved boolean.
+ * @throws when the value is present but not a boolean.
+ */
+export declare function optionalBoolean(args: Readonly<Record<string, unknown>>, key: string, fallback: boolean): boolean;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAErG,8BAA8B;AAC9B,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAChD,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,MAAM,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;IACzE;;;;;OAKG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,GAAG,SAAS,CAAA;AAEnF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjF,MAAM,CAOR;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACtD,MAAM,GAAG,SAAS,CAOpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,OAAO,GAChB,OAAO,CAKT"}

package/lib/adapters/types.js

@@ -0,0 +1,85 @@
+/**
+ * The adapter seam: how one catalog model is actually invoked.
+ *
+ * An adapter is responsible for exactly two things — loading its model lazily
+ * and turning validated tool arguments into the canonical JSON value the tool
+ * declares. Everything else (which models exist, whether they may run, what the
+ * model sees) belongs to the catalog, the capability resolver, and the
+ * registrar.
+ *
+ * @module @try-works/dsh-model-as-tool/adapters/types
+ */
+/**
+ * Reject an aborted call before doing model work.
+ * @param signal - caller cancellation.
+ * @throws the abort reason when the signal is already aborted.
+ */
+export function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw signal.reason instanceof Error ? signal.reason : new Error('aborted');
+}
+/**
+ * Read a required string argument.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @returns the string value.
+ * @throws when the value is absent or not a string.
+ */
+export function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`argument "${key}" must be a non-empty string`);
+    }
+    return value;
+}
+/**
+ * Read an optional integer argument, clamped to a range.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param options - inclusive bounds and the value to use when absent.
+ * @returns the resolved integer.
+ * @throws when the value is present but not an integer in range.
+ */
+export function optionalInteger(args, key, options) {
+    const value = args[key];
+    if (value === undefined)
+        return options.fallback;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < options.min || value > options.max) {
+        throw new Error(`argument "${key}" must be an integer between ${options.min} and ${options.max}`);
+    }
+    return value;
+}
+/**
+ * Read an optional number in a range.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param options - inclusive bounds.
+ * @returns the resolved number, or undefined when absent.
+ * @throws when the value is present but not a finite number in range.
+ */
+export function optionalNumber(args, key, options) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < options.min || value > options.max) {
+        throw new Error(`argument "${key}" must be a number between ${options.min} and ${options.max}`);
+    }
+    return value;
+}
+/**
+ * Read a required boolean argument.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param fallback - value used when the argument is absent.
+ * @returns the resolved boolean.
+ * @throws when the value is present but not a boolean.
+ */
+export function optionalBoolean(args, key, fallback) {
+    const value = args[key];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        throw new Error(`argument "${key}" must be a boolean`);
+    return value;
+}
+//# sourceMappingURL=types.js.map

package/lib/adapters/voz.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Voz adapter — on-device speech recognition with word timestamps.
+ *
+ * Voz has no prebuilt Node core; it runs the same WebAssembly/ONNX Runtime
+ * pipeline everywhere and requires the caller to hand it an ONNX Runtime
+ * module. `onnxruntime-node` ships win32-x64 binaries, which is what makes Voz
+ * the one audio model that works on Windows.
+ *
+ * Loading is expensive (the weights are ~349 MB and ONNX Runtime compiles three
+ * graphs), so the instance is cached for the process and reused.
+ *
+ * @module @try-works/dsh-model-as-tool/adapters/voz
+ */
+import type { ModelCatalogEntry } from '../types.ts';
+import { type ModelAdapter } from './types.ts';
+/**
+ * Build the Voz adapter.
+ * @param entry - the catalog entry this adapter serves.
+ * @returns the adapter, or undefined if the entry is not Voz.
+ */
+export declare function createVozAdapter(entry: ModelCatalogEntry): ModelAdapter | undefined;
+//# sourceMappingURL=voz.d.ts.map

package/lib/adapters/voz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voz.d.ts","sourceRoot":"","sources":["../../src/adapters/voz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAmCnB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,SAAS,CA+DnF"}

package/lib/adapters/voz.js

@@ -0,0 +1,90 @@
+/**
+ * Voz adapter — on-device speech recognition with word timestamps.
+ *
+ * Voz has no prebuilt Node core; it runs the same WebAssembly/ONNX Runtime
+ * pipeline everywhere and requires the caller to hand it an ONNX Runtime
+ * module. `onnxruntime-node` ships win32-x64 binaries, which is what makes Voz
+ * the one audio model that works on Windows.
+ *
+ * Loading is expensive (the weights are ~349 MB and ONNX Runtime compiles three
+ * graphs), so the instance is cached for the process and reused.
+ *
+ * @module @try-works/dsh-model-as-tool/adapters/voz
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { optionalBoolean, requireString, throwIfAborted, } from "./types.js";
+/** Cap on the words returned inline, so a long recording cannot flood the context. */
+const MAX_WORDS = 2000;
+/**
+ * Build the Voz adapter.
+ * @param entry - the catalog entry this adapter serves.
+ * @returns the adapter, or undefined if the entry is not Voz.
+ */
+export function createVozAdapter(entry) {
+    if (entry.id !== 'voz')
+        return undefined;
+    let loaded;
+    const load = async () => {
+        loaded ??= (async () => {
+            try {
+                // Both specifiers are variables for the same reason as Tongue: each is
+                // an optional dependency that may legitimately be absent.
+                const runtimeSpecifier = entry.requiresRuntime[0] ?? 'onnxruntime-node';
+                const ort = await import(__rewriteRelativeImportExtension(runtimeSpecifier));
+                const module = await import(__rewriteRelativeImportExtension(entry.npmPackage));
+                return await module.Voz.load({ ort });
+            }
+            catch (error) {
+                loaded = undefined;
+                throw new Error(`Voz could not be loaded: ${error instanceof Error ? error.message : String(error)}. `
+                    + 'Voz needs onnxruntime-node installed beside the plugin.');
+            }
+        })();
+        return loaded;
+    };
+    return {
+        modelId: entry.id,
+        async invoke({ args, signal }) {
+            throwIfAborted(signal);
+            const audioPath = requireString(args, 'audio_path');
+            const includeWords = optionalBoolean(args, 'include_words', true);
+            const voz = await load();
+            throwIfAborted(signal);
+            const result = await voz.transcribe(audioPath);
+            throwIfAborted(signal);
+            const value = {
+                text: result.text,
+                wordCount: result.words?.length ?? 0,
+            };
+            if (typeof result.realtimeFactor === 'number') {
+                value.realtimeFactor = result.realtimeFactor;
+            }
+            if (includeWords) {
+                const words = result.words ?? [];
+                value.words = words.slice(0, MAX_WORDS).map(word => ({
+                    text: word.text,
+                    start: word.start,
+                    end: word.end,
+                }));
+                if (words.length > MAX_WORDS)
+                    value.wordsTruncated = true;
+            }
+            return value;
+        },
+        async dispose() {
+            if (loaded === undefined)
+                return;
+            const instance = await loaded.catch(() => undefined);
+            instance?.dispose?.();
+            loaded = undefined;
+        },
+    };
+}
+//# sourceMappingURL=voz.js.map

package/lib/capability.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Capability resolution: decide whether a catalog model can actually run in
+ * this DSH process, and by which route.
+ *
+ * The rule this module enforces is that a model becomes a tool only when an
+ * adapter can really invoke it. Every other model stays catalogued and
+ * reportable, so `model_tools` can explain what is missing instead of the agent
+ * discovering a broken tool at call time.
+ *
+ * @module @try-works/dsh-model-as-tool/capability
+ */
+import type { CapabilityVerdict, ModelCatalogEntry } from './types.ts';
+/**
+ * Whether a package specifier resolves from this plugin's installation.
+ *
+ * Resolution deliberately does not load the module: importing a model package
+ * pulls in a WASM or native runtime, and capability probing must stay cheap
+ * enough to run at plugin load.
+ * @param specifier - package name, optionally with a subpath.
+ * @returns whether Node can resolve the specifier.
+ */
+export declare function canResolve(specifier: string): boolean;
+/** Join a package and its documented subpath into one specifier. */
+export declare function packageSpecifier(pkg: string, subpath: string | null): string;
+/**
+ * Resolve how (and whether) one model can run here.
+ *
+ * Transport preference is deliberate: an in-process package is fastest and
+ * needs no external service, so it wins; the CLI is local but out-of-process;
+ * the bridge is last because it depends on another machine. A user who would
+ * rather route everything through a bridge can disable the other two.
+ * @param entry - the catalog entry to resolve.
+ * @param options - overrides for testing; `resolve`, `platform` and the transport switches replace the process facts.
+ * @returns the verdict, including the reason for every negative one.
+ */
+export declare function resolveCapability(entry: ModelCatalogEntry, options?: {
+    readonly resolve?: (specifier: string) => boolean;
+    readonly platform?: NodeJS.Platform;
+    /** Whether the Desert Ant CLI is on PATH. */
+    readonly cliAvailable?: boolean;
+    /** Whether a bridge endpoint is configured. */
+    readonly remoteEndpoint?: string | undefined;
+    /** Turn off in-process npm resolution, to force another transport. */
+    readonly allowNpm?: boolean;
+}): CapabilityVerdict;
+/** One model plus its resolved capability verdict. */
+export interface ResolvedModel {
+    readonly entry: ModelCatalogEntry;
+    readonly verdict: CapabilityVerdict;
+}
+/**
+ * Resolve every catalog entry.
+ * @param entries - validated catalog entries.
+ * @param options - resolution overrides, forwarded to {@link resolveCapability}.
+ * @returns one record per entry, in catalog order.
+ */
+export declare function resolveCatalog(entries: readonly ModelCatalogEntry[], options?: Parameters<typeof resolveCapability>[1]): ResolvedModel[];
+//# sourceMappingURL=capability.d.ts.map

package/lib/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAWtE;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE5E;AAwBD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,iBAAiB,EACxB,OAAO,GAAE;IACP,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAA;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CACvB,GACL,iBAAiB,CA6FnB;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,OAAO,GAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAM,GACpD,aAAa,EAAE,CAEjB"}