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

package/lib/bindings.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Contract-driven registration: one tool per contract, not one per model.
+ *
+ * This is the host half of BASE-02. The contract decides the tool's name, schema
+ * and description; the implementation behind it is host configuration. A second
+ * model implementing `stt.transcribe` therefore joins the existing
+ * `stt_transcribe` tool rather than appearing as a competing duplicate — which is
+ * the behaviour the previous per-model registrar could not express.
+ *
+ * The host also owns provenance (DECL-03): `meta` is stamped here, from host
+ * state, so an implementation cannot claim another package's identity.
+ *
+ * @module @try-works/dsh-tool-mode/bindings
+ */
+import { type ExecutionLocation, type ToolContract, type ToolMeta } from '@try-works/tool-mode-contracts';
+import type { ModelCatalogEntry, ModelRoute } from './types.ts';
+import { type InvocationReceipt } from './receipt.ts';
+import { type InvocationAuthority, type ToolGrant } from './authority.ts';
+import type { ModelAdapter } from './adapters/index.ts';
+/** Host identity stamped into every result. */
+export interface HostIdentity {
+    /** The host package name. */
+    readonly extension: string;
+    /** The host package version. */
+    readonly extensionVersion: string;
+    /** Activation generation, incremented when the tool surface changes. */
+    readonly activationGeneration: number;
+    /** Receipt id factory; injectable so tests are deterministic. */
+    readonly nextReceiptId: () => string;
+    /**
+     * The grant this tool surface runs under (SEC-03).
+     *
+     * Built by the host from operator configuration. A caller's request cannot
+     * reach it, which is what makes the authority trustworthy (BASE-05).
+     */
+    readonly grant: ToolGrant;
+    /** How the host classified this caller. */
+    readonly callerKind: InvocationAuthority['callerKind'];
+    /**
+     * Where an invocation receipt is delivered (EXT-35).
+     *
+     * Optional so a host without a receipt store still works; when present it sees one
+     * receipt per SUCCESSFUL call, which is what makes the provenance recoverable
+     * after the fact rather than only during the call.
+     */
+    readonly recordReceipt?: (receipt: InvocationReceipt) => void;
+}
+/** One contract with the implementation chosen to serve it. */
+export interface ContractBinding {
+    /** The contract that defines the tool. */
+    readonly contract: ToolContract;
+    /** The catalog entry selected to execute it. */
+    readonly implementation: ModelCatalogEntry;
+    /** The adapter that invokes that model. */
+    readonly adapter: ModelAdapter;
+    /** The route the capability resolver proved, used for `executionLocation`. */
+    readonly route: ModelRoute;
+    /** Other runnable implementations of the same contract, for reporting. */
+    readonly alternatives: readonly string[];
+}
+/**
+ * Translate a resolver route into the caller-facing execution location (SPEC §6).
+ *
+ * "Local" is deliberately not one value: a bridge is another machine, and a
+ * caller reasoning about data boundaries needs to know which.
+ * @param route - the resolved route.
+ * @returns the declared execution location.
+ */
+export declare function executionLocationOf(route: ModelRoute): ExecutionLocation;
+/**
+ * Build the `meta` envelope for one execution.
+ *
+ * Every field comes from host state or the contract, never from the model's
+ * output, which is what makes the provenance trustworthy (DECL-03).
+ * @param binding - the contract and implementation that are executing.
+ * @param host - the host identity to stamp.
+ * @param warnings - non-fatal conditions observed during this call.
+ * @returns the envelope.
+ */
+export declare function buildMeta(binding: Pick<ContractBinding, 'contract' | 'implementation' | 'route'>, host: HostIdentity, warnings?: readonly string[]): ToolMeta;
+/**
+ * Build the EXT-35 receipt for one call.
+ *
+ * Separate from {@link buildMeta} because it answers a different question: the
+ * envelope says what the caller received, while the receipt says what RAN and from
+ * which bytes. The extra provenance — the extension package, its content digest,
+ * the model and recipe identity — is what makes a receipt usable after the fact,
+ * when the version alone no longer identifies the code.
+ * @param binding - the contract and the implementation chosen for it.
+ * @param host - host identity and the receipt factory.
+ * @param meta - the envelope already stamped, for the receipt identity.
+ * @returns the invocation receipt.
+ */
+export declare function buildReceipt(binding: Pick<ContractBinding, 'contract' | 'implementation' | 'route'>, host: HostIdentity, meta: Pick<ToolMeta, 'receiptId'>, warnings?: readonly string[]): InvocationReceipt;
+/**
+ * Register one contract as a single DSH tool.
+ *
+ * The tool body validates arguments against the contract, applies the cross-field
+ * rules the DSH DSL cannot express, invokes the selected implementation, then
+ * validates the RESULT before returning it. A violation surfaces as a tool
+ * failure rather than as malformed data reaching a caller (AT-11).
+ * @param ctx - the context whose tool registry receives the definition.
+ * @param binding - the contract and the implementation chosen for it.
+ * @param host - host identity to stamp into results.
+ * @returns the registered tool name and the registry disposer.
+ */
+export declare function registerContractTool(ctx: {
+    tools: {
+        register(definition: unknown): () => void;
+    };
+}, binding: ContractBinding, host: HostIdentity): {
+    toolName: string;
+    dispose: () => void;
+};
+/**
+ * Register a STANDARD contract tool served by an ACTIVE extension's
+ * IMPLEMENTATION (TASK-121), mirroring {@link registerContractTool} with the
+ * execution bound to a host-supplied dispatch instead of a catalogue adapter.
+ *
+ * The tool name, description and schemas come from the CONTRACT definition —
+ * never invented per extension — and the dispatch hands the CONTRACT-shaped
+ * input to the extension's implementation (the extension reads the standard
+ * shapes directly). Input/output validation, the grant authorization, the
+ * meta stamping and the receipt are the SAME discipline the catalogue path
+ * applies, so the two routes cannot diverge.
+ * @param ctx - the context whose tool registry receives the definition.
+ * @param contract - the standard contract definition.
+ * @param host - host identity to stamp into results.
+ * @param dispatch - executes through the extension implementation.
+ * @returns the registered tool name and the registry disposer.
+ */
+export declare function registerContractImplementationTool(ctx: {
+    tools: {
+        register(definition: unknown): () => void;
+    };
+}, contract: ToolContract, host: HostIdentity, dispatch: (args: Record<string, unknown>, signal: AbortSignal) => Promise<Record<string, unknown>>, implementation: {
+    readonly id: string;
+    readonly extensionId: string;
+    readonly modelId: string;
+}): {
+    toolName: string;
+    dispose: () => void;
+};
+//# sourceMappingURL=bindings.d.ts.map

package/lib/bindings.d.ts.map

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

package/lib/bindings.js

@@ -0,0 +1,314 @@
+/**
+ * Contract-driven registration: one tool per contract, not one per model.
+ *
+ * This is the host half of BASE-02. The contract decides the tool's name, schema
+ * and description; the implementation behind it is host configuration. A second
+ * model implementing `stt.transcribe` therefore joins the existing
+ * `stt_transcribe` tool rather than appearing as a competing duplicate — which is
+ * the behaviour the previous per-model registrar could not express.
+ *
+ * The host also owns provenance (DECL-03): `meta` is stamped here, from host
+ * state, so an implementation cannot claim another package's identity.
+ *
+ * @module @try-works/dsh-tool-mode/bindings
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { assertValidContract, assertValidInput, assertValidOutput, crossFieldRules, projectSchemaToDsh, toDshParameters, } from '@try-works/tool-mode-contracts';
+import { toContractPayload, toNativeArgs } from "./contract-payload.js";
+import { buildInvocationReceipt } from "./receipt.js";
+import { authorizeTool, createInvocationAuthority, } from "./authority.js";
+/**
+ * Translate a resolver route into the caller-facing execution location (SPEC §6).
+ *
+ * "Local" is deliberately not one value: a bridge is another machine, and a
+ * caller reasoning about data boundaries needs to know which.
+ * @param route - the resolved route.
+ * @returns the declared execution location.
+ */
+export function executionLocationOf(route) {
+    switch (route) {
+        case 'extension':
+        case 'npm-native':
+        case 'npm-onnxruntime':
+            return 'host';
+        case 'cli':
+            return 'host';
+        case 'remote':
+            return 'team-server';
+        /* v8 ignore next -- closed union; a new route must fail compilation here. */
+        default:
+            return 'host';
+    }
+}
+/**
+ * Build the `meta` envelope for one execution.
+ *
+ * Every field comes from host state or the contract, never from the model's
+ * output, which is what makes the provenance trustworthy (DECL-03).
+ * @param binding - the contract and implementation that are executing.
+ * @param host - the host identity to stamp.
+ * @param warnings - non-fatal conditions observed during this call.
+ * @returns the envelope.
+ */
+export function buildMeta(binding, host, warnings = []) {
+    return {
+        contract: binding.contract.contract,
+        contractVersion: binding.contract.version,
+        implementationId: binding.implementation.id,
+        extension: host.extension,
+        extensionVersion: host.extensionVersion,
+        activationGeneration: host.activationGeneration,
+        executionLocation: executionLocationOf(binding.route),
+        receiptId: host.nextReceiptId(),
+        warnings: [...warnings],
+    };
+}
+/**
+ * Build the EXT-35 receipt for one call.
+ *
+ * Separate from {@link buildMeta} because it answers a different question: the
+ * envelope says what the caller received, while the receipt says what RAN and from
+ * which bytes. The extra provenance — the extension package, its content digest,
+ * the model and recipe identity — is what makes a receipt usable after the fact,
+ * when the version alone no longer identifies the code.
+ * @param binding - the contract and the implementation chosen for it.
+ * @param host - host identity and the receipt factory.
+ * @param meta - the envelope already stamped, for the receipt identity.
+ * @returns the invocation receipt.
+ */
+export function buildReceipt(binding, host, meta, warnings = []) {
+    return buildInvocationReceipt({
+        receiptId: meta.receiptId,
+        contract: binding.contract.contract,
+        contractVersion: binding.contract.version,
+        implementationId: binding.implementation.id,
+        extension: binding.implementation.provider?.extension
+            ?? host.extension,
+        extensionVersion: host.extensionVersion,
+        // The catalog carries no digest, so it is reported as unknown rather than
+        // invented. A receipt that guesses at provenance is worse than one that admits
+        // it does not have it.
+        extensionContentDigest: null,
+        dependencyLockDigest: null,
+        modelIdentity: binding.implementation.provider?.modelId ?? binding.implementation.id,
+        recipeVersion: null,
+        activationGeneration: host.activationGeneration,
+        executionLocation: executionLocationOf(binding.route),
+        warnings,
+    });
+}
+/**
+ * Register one contract as a single DSH tool.
+ *
+ * The tool body validates arguments against the contract, applies the cross-field
+ * rules the DSH DSL cannot express, invokes the selected implementation, then
+ * validates the RESULT before returning it. A violation surfaces as a tool
+ * failure rather than as malformed data reaching a caller (AT-11).
+ * @param ctx - the context whose tool registry receives the definition.
+ * @param binding - the contract and the implementation chosen for it.
+ * @param host - host identity to stamp into results.
+ * @returns the registered tool name and the registry disposer.
+ */
+export function registerContractTool(ctx, binding, host) {
+    const { contract, adapter, implementation } = binding;
+    // Registration and argument validation must agree, so the contract is checked
+    // here rather than trusted: a definition that cannot compile would otherwise
+    // fail only when a caller happened to hit the broken branch.
+    assertValidContract(contract);
+    const rules = crossFieldRules(contract);
+    const definition = defineTool({
+        name: contract.toolName,
+        description: contract.description,
+        // `toDshParameters` returns the projected JSON-Schema subset; the registry's
+        // DSL type is structurally narrower, and `ProjectionError` has already
+        // refused any keyword the DSL cannot express.
+        parameters: toDshParameters(contract),
+        output: {
+            /**
+             * The PROJECTED output schema, closing the DECL-02 advertisement gap.
+             *
+             * The registry validates every success against this advertised schema, so it may
+             * never be STRICTER than the contract. `projectSchemaToDsh` only loosens: it drops
+             * keywords the DSH value-schema DSL cannot carry (`items` at depth, non-scalar
+             * `enum`, `minimum`/`pattern`/`minLength`), records each in `runtimeEnforced`, and
+             * keeps every property name, type and closedness. `assertValidOutput` still
+             * enforces the FULL contract at runtime, so the projection is advertisement-only.
+             *
+             * The open `{type:"object", additionalProperties:true}` this replaces declared
+             * nothing about any field; the projection names every property, its type and its
+             * requiredness — a genuine declaration. Registration was previously impossible
+             * because the projection mangled scalar enums into objects (`{0:'host',...}`) via
+             * an array/record confusion in stripItems; that defect is fixed and probed.
+             */
+            schema: {
+                type: 'object',
+                properties: projectSchemaToDsh(contract.outputSchema).parameters,
+                additionalProperties: false,
+            },
+            render: (_args, value) => {
+                const record = value;
+                return [{ type: 'text', text: renderForModel(contract, record) }];
+            },
+        },
+        async execute(args, exec) {
+            const record = args;
+            assertValidInput(contract, record);
+            for (const rule of rules) {
+                const violation = rule(record);
+                if (violation !== undefined) {
+                    throw new Error(`${contract.toolName}: ${violation}`);
+                }
+            }
+            // SEC-03: the grant is consulted before any work happens, so an ungranted
+            // tool is refused before inference rather than after it.
+            authorizeTool(host.grant, contract.toolName);
+            const authority = createInvocationAuthority(host.grant, host.callerKind);
+            // The contract's caller-facing arguments are translated into the adapter's
+            // native vocabulary before invocation; the reverse translation runs on the
+            // result. Both are explicit, so a name change on either side is a compile-
+            // or test-time failure rather than a runtime mystery.
+            const nativeArgs = toNativeArgs(contract.contract, record);
+            const native = await adapter.invoke({ args: nativeArgs, signal: exec.signal, authority });
+            // The implementation's native result is translated into the contract's
+            // payload before validation: the contract is the authority, so a mismatch is
+            // resolved here rather than by loosening the schema.
+            const payload = toContractPayload(contract.contract, native, record);
+            // `ToolMeta` is a plain interface without an index signature, so it is not
+            // structurally a `JsonValue`; the value is losslessly JSON either way, and
+            // `assertValidOutput` is the real check.
+            const meta = buildMeta(binding, host);
+            const value = { ...payload, meta };
+            assertValidOutput(contract, value);
+            // EXT-35: the receipt is emitted once the call SUCCEEDED. A receipt for a
+            // call that failed validation would claim provenance for a result nobody
+            // received, so the sink sees only calls that actually completed.
+            host.recordReceipt?.(buildReceipt(binding, host, meta));
+            /**
+             * The cast exists because the projected schema's inferred type is a closed
+             * record, while the registry validates the VALUE against the projected schema
+             * (which only LOOSENS the contract) and `assertValidOutput` enforces the full
+             * contract. The value is losslessly JSON and has passed both; the type-level
+             * fiction is contained to this return.
+             */
+            return value;
+        },
+        presentCall(callArgs) {
+            const primary = Object.values(callArgs)[0];
+            return {
+                card: 'generic',
+                title: contract.toolName,
+                kind: 'read',
+                ...typeof primary === 'string' ? { rawInput: primary } : {},
+            };
+        },
+    });
+    void implementation;
+    return { toolName: contract.toolName, dispose: ctx.tools.register(definition) };
+}
+/**
+ * Register a STANDARD contract tool served by an ACTIVE extension's
+ * IMPLEMENTATION (TASK-121), mirroring {@link registerContractTool} with the
+ * execution bound to a host-supplied dispatch instead of a catalogue adapter.
+ *
+ * The tool name, description and schemas come from the CONTRACT definition —
+ * never invented per extension — and the dispatch hands the CONTRACT-shaped
+ * input to the extension's implementation (the extension reads the standard
+ * shapes directly). Input/output validation, the grant authorization, the
+ * meta stamping and the receipt are the SAME discipline the catalogue path
+ * applies, so the two routes cannot diverge.
+ * @param ctx - the context whose tool registry receives the definition.
+ * @param contract - the standard contract definition.
+ * @param host - host identity to stamp into results.
+ * @param dispatch - executes through the extension implementation.
+ * @returns the registered tool name and the registry disposer.
+ */
+export function registerContractImplementationTool(ctx, contract, host, dispatch, implementation) {
+    assertValidContract(contract);
+    const rules = crossFieldRules(contract);
+    // The minimal binding-lite the provenance builders read: the meta names the
+    // extension's implementation, and the receipt records the extension package.
+    const bindingLite = {
+        contract,
+        implementation: {
+            id: implementation.id,
+            provider: { extension: implementation.extensionId, modelId: implementation.modelId },
+        },
+        route: 'extension',
+    };
+    const definition = defineTool({
+        name: contract.toolName,
+        description: contract.description,
+        parameters: toDshParameters(contract),
+        output: {
+            schema: {
+                type: 'object',
+                properties: projectSchemaToDsh(contract.outputSchema).parameters,
+                additionalProperties: false,
+            },
+            render: (_args, value) => {
+                const record = value;
+                return [{ type: 'text', text: renderForModel(contract, record) }];
+            },
+        },
+        async execute(args, exec) {
+            const record = args;
+            assertValidInput(contract, record);
+            for (const rule of rules) {
+                const violation = rule(record);
+                if (violation !== undefined) {
+                    throw new Error(`${contract.toolName}: ${violation}`);
+                }
+            }
+            authorizeTool(host.grant, contract.toolName);
+            const value = await dispatch(record, exec.signal);
+            const meta = buildMeta(bindingLite, host);
+            const stamped = { ...value, meta };
+            assertValidOutput(contract, stamped);
+            host.recordReceipt?.(buildReceipt(bindingLite, host, meta));
+            return stamped;
+        },
+        presentCall(callArgs) {
+            const primary = Object.values(callArgs)[0];
+            return {
+                card: 'generic',
+                title: contract.toolName,
+                kind: 'read',
+                ...typeof primary === 'string' ? { rawInput: primary } : {},
+            };
+        },
+    });
+    return { toolName: contract.toolName, dispose: ctx.tools.register(definition) };
+}
+/**
+ * Render a contract result for the model.
+ *
+ * The canonical value is the source of truth; this only chooses the presentation.
+ * It never invents a field the contract did not declare.
+ * @param contract - the contract that produced the value.
+ * @param value - the validated canonical value.
+ * @returns a short text projection.
+ */
+function renderForModel(contract, value) {
+    if (contract.contract === 'text.language_detect') {
+        const language = value.language;
+        const candidates = Array.isArray(value.candidates) ? value.candidates : [];
+        const detail = candidates
+            .filter((candidate) => typeof candidate === 'object' && candidate !== null
+            && typeof candidate.language === 'string')
+            .map(candidate => `${candidate.language} ${(candidate.probability * 100).toFixed(1)}%`)
+            .join(', ');
+        const tooClose = value.tooCloseToCall === true ? ' (too close to call)' : '';
+        return `Detected language: ${String(language)}${tooClose}`
+            + (detail.length > 0 ? `\nCandidates: ${detail}` : '');
+    }
+    if (contract.contract === 'stt.transcribe') {
+        const text = typeof value.text === 'string' ? value.text : '';
+        const coverage = value.coverage;
+        const partial = coverage?.complete === false
+            ? `\n[warnings] partial transcript: ${String(coverage.transcribedSeconds ?? 0)}s covered\n`
+            : '';
+        return text.length > 0 ? `${text}${partial}` : `(no speech recognized)${partial}`;
+    }
+    return JSON.stringify(value, null, 2);
+}
+//# sourceMappingURL=bindings.js.map

package/lib/builtins.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Host-release trusted built-ins (EXT-03).
+ *
+ * The lock is read from the HOST package, never from an extension manifest, so a
+ * package cannot grant itself built-in status or extra trust by declaring it.
+ * A missing/malformed lock fails closed with an empty protected set.
+ */
+/** One trusted built-in entry. */
+export interface BuiltinEntry {
+    readonly extensionId: string;
+    readonly package?: string;
+    readonly protected: boolean;
+}
+/** The host-release built-ins lock. */
+export interface BuiltinsLock {
+    readonly version: number;
+    readonly builtins: readonly BuiltinEntry[];
+}
+/** Read and validate the lock next to this module. */
+export declare function loadBuiltinsLock(url?: URL): BuiltinsLock;
+/** The lock shipped with this host release. */
+export declare const BUILTINS_LOCK: BuiltinsLock;
+/** Extension ids the host release protects from uninstall. */
+export declare const PROTECTED_BUILTIN_IDS: readonly string[];
+/** Whether an extension is a protected built-in of THIS host release. */
+export declare function isProtectedBuiltin(extensionId: string): boolean;
+//# sourceMappingURL=builtins.d.ts.map

package/lib/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,kCAAkC;AAClC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAC3C;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,GAAuD,GAAG,YAAY,CAkB3G;AAED,+CAA+C;AAC/C,eAAO,MAAM,aAAa,EAAE,YAAiC,CAAA;AAE7D,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAElD,CAAA;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE/D"}

package/lib/builtins.js

@@ -0,0 +1,37 @@
+/**
+ * Host-release trusted built-ins (EXT-03).
+ *
+ * The lock is read from the HOST package, never from an extension manifest, so a
+ * package cannot grant itself built-in status or extra trust by declaring it.
+ * A missing/malformed lock fails closed with an empty protected set.
+ */
+import { readFileSync } from 'node:fs';
+/** Read and validate the lock next to this module. */
+export function loadBuiltinsLock(url = new URL('../builtins.lock.json', import.meta.url)) {
+    const parsed = JSON.parse(readFileSync(url, 'utf8'));
+    if (parsed.version !== 1 || !Array.isArray(parsed.builtins)) {
+        throw new Error('builtins.lock.json must carry version 1 and a builtins array');
+    }
+    const builtins = parsed.builtins.map((entry, index) => {
+        if (entry === null || typeof entry !== 'object') {
+            throw new Error(`builtins.lock.json builtins[${index}] is not an object`);
+        }
+        if (typeof entry.extensionId !== 'string' || entry.extensionId.length === 0) {
+            throw new Error(`builtins.lock.json builtins[${index}].extensionId must be a non-empty string`);
+        }
+        if (typeof entry.protected !== 'boolean') {
+            throw new Error(`builtins.lock.json builtins[${index}].protected must be a boolean`);
+        }
+        return { ...entry };
+    });
+    return { version: 1, builtins };
+}
+/** The lock shipped with this host release. */
+export const BUILTINS_LOCK = loadBuiltinsLock();
+/** Extension ids the host release protects from uninstall. */
+export const PROTECTED_BUILTIN_IDS = Object.freeze(BUILTINS_LOCK.builtins.filter(entry => entry.protected).map(entry => entry.extensionId));
+/** Whether an extension is a protected built-in of THIS host release. */
+export function isProtectedBuiltin(extensionId) {
+    return PROTECTED_BUILTIN_IDS.includes(extensionId);
+}
+//# sourceMappingURL=builtins.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-tool-mode/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,CA+GnB;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"}