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

package/lib/mcp-usage.js

@@ -0,0 +1,189 @@
+/**
+ * The bounded external-MCP call ledger (plan §3.4).
+ *
+ * External MCP `tools/call`s are not session events, so the only honest way to answer
+ * "MCP was used, by whom, how often" is to persist them. One JSONL row per call, trimmed
+ * at a bound, written beside the host state.
+ *
+ * The record TYPE is the privacy boundary: it has identity, timings, failure class,
+ * sizes and the receipt id, and deliberately nowhere to put arguments, results,
+ * credentials or the bearer token. A future change cannot start logging payloads by
+ * accident without changing this type.
+ *
+ * @module @try-works/dsh-tool-mode/mcp-usage
+ */
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** How many rows the ledger retains. */
+export const MCP_USAGE_MAX_ROWS = 5_000;
+/** The default page size for a call-log request. */
+export const MCP_USAGE_DEFAULT_PAGE_SIZE = 50;
+/** What the accounting hook supplies, plus the tool name it now carries. */
+export function recordFromAccounting(toolName, accounting, time = Date.now()) {
+    return {
+        time,
+        tool: toolName,
+        clientId: accounting.clientId ?? 'unknown',
+        grantId: accounting.grantId ?? null,
+        totalMs: accounting.timings.totalMs,
+        queuedMs: accounting.timings.queuedMs,
+        loadMs: accounting.timings.loadMs,
+        inferenceMs: accounting.timings.inferenceMs,
+        failureClass: accounting.failureClass,
+        reason: accounting.reason,
+        inputBytes: accounting.sizes.inputBytes,
+        outputBytes: accounting.sizes.outputBytes,
+        receiptId: accounting.receiptId,
+    };
+}
+/** A finite number, else null. */
+function numberOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/** Read one raw ledger line as a record, or null when it is not one. */
+function readRecord(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    // SAFETY: the guard above proved a non-null, non-array object; every field the record
+    // needs is type-checked below before it is copied into the typed result.
+    const record = parsed;
+    const time = numberOrNull(record['time']);
+    const totalMs = numberOrNull(record['totalMs']);
+    if (time === null || totalMs === null)
+        return null;
+    if (typeof record['tool'] !== 'string' || typeof record['clientId'] !== 'string')
+        return null;
+    if (typeof record['receiptId'] !== 'string' || typeof record['failureClass'] !== 'string')
+        return null;
+    return {
+        time,
+        tool: record['tool'],
+        clientId: record['clientId'],
+        grantId: typeof record['grantId'] === 'string' ? record['grantId'] : null,
+        totalMs,
+        queuedMs: numberOrNull(record['queuedMs']) ?? 0,
+        loadMs: numberOrNull(record['loadMs']) ?? 0,
+        inferenceMs: numberOrNull(record['inferenceMs']) ?? 0,
+        failureClass: record['failureClass'],
+        reason: typeof record['reason'] === 'string' ? record['reason'] : null,
+        inputBytes: numberOrNull(record['inputBytes']) ?? 0,
+        outputBytes: numberOrNull(record['outputBytes']) ?? 0,
+        receiptId: record['receiptId'],
+    };
+}
+/**
+ * A bounded JSONL ledger over one file.
+ *
+ * Operations are synchronous and defensive: an unreadable or corrupt line contributes
+ * nothing, and a rotated file keeps the newest rows rather than failing the append.
+ */
+export class McpUsageLedger {
+    #file;
+    #maxRows;
+    /**
+     * @param file - the JSONL path.
+     * @param options - `maxRows` defaults to {@link MCP_USAGE_MAX_ROWS}.
+     */
+    constructor(file, options = {}) {
+        this.#file = file;
+        this.#maxRows = Math.max(2, options.maxRows ?? MCP_USAGE_MAX_ROWS);
+    }
+    /** The ledger path (the MCP status surface names it, never its contents). */
+    get file() {
+        return this.#file;
+    }
+    /** All readable rows, oldest first. */
+    #rows() {
+        let text;
+        try {
+            text = readFileSync(this.#file, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const rows = [];
+        for (const line of text.split('\n')) {
+            if (line.trim().length === 0)
+                continue;
+            const record = readRecord(line);
+            if (record !== null)
+                rows.push(record);
+        }
+        return rows;
+    }
+    /** Atomically replace the file with exactly these rows. */
+    #write(rows) {
+        mkdirSync(dirname(this.#file), { recursive: true });
+        const temporary = `${this.#file}.${process.pid}.${Date.now().toString(36)}.tmp`;
+        writeFileSync(temporary, rows.map(row => `${JSON.stringify(row)}\n`).join(''), 'utf8');
+        renameSync(temporary, this.#file);
+    }
+    /**
+     * Append one call, trimming at the bound.
+     * @param call - the record to persist.
+     */
+    record(call) {
+        mkdirSync(dirname(this.#file), { recursive: true });
+        const existing = this.#rows();
+        if (existing.length >= this.#maxRows) {
+            // Rotation: keep the newest (bound - 1) rows, then append the new one.
+            this.#write([...existing.slice(existing.length - (this.#maxRows - 1)), call]);
+            return;
+        }
+        appendFileSync(this.#file, `${JSON.stringify(call)}\n`, 'utf8');
+    }
+    /**
+     * Read one page, newest first.
+     * @param query - optional client filter and 1-based page.
+     * @returns the page plus the matching total and the ledger's client identities.
+     */
+    read(query = {}) {
+        const all = this.#rows();
+        const clients = [...new Set(all.map(row => row.clientId))].sort((left, right) => left.localeCompare(right));
+        const matching = query.clientId === undefined ? all : all.filter(row => row.clientId === query.clientId);
+        const page = Math.max(1, Math.trunc(query.page ?? 1));
+        const pageSize = Math.min(200, Math.max(1, Math.trunc(query.pageSize ?? MCP_USAGE_DEFAULT_PAGE_SIZE)));
+        const newestFirst = [...matching].reverse();
+        const start = (page - 1) * pageSize;
+        return {
+            calls: newestFirst.slice(start, start + pageSize),
+            total: matching.length,
+            page,
+            pageSize,
+            clients,
+        };
+    }
+    /** Aggregate the ledger by client and tool. */
+    summarize() {
+        const rows = this.#rows();
+        const clients = new Map();
+        const tools = new Map();
+        for (const row of rows) {
+            const client = clients.get(row.clientId) ?? { calls: 0, errors: 0, lastSeen: 0, grantId: null };
+            clients.set(row.clientId, {
+                calls: client.calls + 1,
+                errors: client.errors + (row.failureClass === 'none' ? 0 : 1),
+                lastSeen: Math.max(client.lastSeen, row.time),
+                grantId: row.grantId ?? client.grantId,
+            });
+            tools.set(row.tool, (tools.get(row.tool) ?? 0) + 1);
+        }
+        return {
+            total: rows.length,
+            clients: [...clients.entries()]
+                .map(([clientId, client]) => ({ clientId, ...client }))
+                .sort((left, right) => left.clientId.localeCompare(right.clientId)),
+            tools: [...tools.entries()]
+                .map(([tool, calls]) => ({ tool, calls }))
+                .sort((left, right) => right.calls - left.calls || left.tool.localeCompare(right.tool)),
+        };
+    }
+}
+//# sourceMappingURL=mcp-usage.js.map

package/lib/model-qualification.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Model qualification and capability resolution (MODEL-01, MODEL-04, MODEL-05, MODEL-06).
+ *
+ * Four rules, each guarding a way of claiming more than is known:
+ *
+ * - **A platform table is not proof of correct inference** (MODEL-05). A record is
+ *   qualified only when the exact revision, artifact hash, tokenizer, processor, engine
+ *   version, ABI and execution provider are all recorded. A missing field is a GAP, and
+ *   a gap is not a qualification.
+ * - **A model's modality list is not an adapter's** (MODEL-05). A model can support
+ *   video while the selected adapter does not, so what is ADVERTISED is the INTERSECTION
+ *   of the two, described as such.
+ * - **A model name is not a capability test** (MODEL-06). Capability comes from the
+ *   resolved model, never from recognising a brand.
+ * - **Unknown is not unsupported** (MODEL-06). The requirement says to record them
+ *   separately, because collapsing them lets an unevaluated capability be reported as a
+ *   known absence — or, worse, the reverse.
+ *
+ * @module @try-works/dsh-tool-mode/model-qualification
+ */
+/**
+ * What is known about one capability.
+ *
+ * Three states rather than two, because MODEL-06 requires unknown and unsupported to be
+ * recorded separately.
+ */
+export type CapabilityState = 
+/** Evaluated, and it works. */
+'supported'
+/** Evaluated, and it does not. */
+ | 'unsupported'
+/** NOT evaluated. Reporting this as either of the others is the defect. */
+ | 'unknown';
+/** A capability of a model or an adapter. */
+export type Modality = 'text' | 'code' | 'image' | 'audio' | 'video' | 'embedding';
+/**
+ * The exact path a model is executed through (MODEL-05).
+ *
+ * Every field is required for qualification, because each one has been the difference
+ * between "the package imports" and "inference is correct".
+ */
+export interface QualificationRecord {
+    /** The model revision, not a branch or floating tag. */
+    readonly modelRevision: string;
+    /** The SHA of the exported artifact that is actually loaded. */
+    readonly artifactSha: string;
+    /** The tokenizer identity. */
+    readonly tokenizer: string;
+    /** The processor or preprocessing recipe identity. */
+    readonly processor: string;
+    /** The engine or package version. */
+    readonly engineVersion: string;
+    /** The Node ABI. */
+    readonly nodeAbi: string;
+    /** The CPU architecture, e.g. `x64`. */
+    readonly architecture: string;
+    /** The execution provider, e.g. `cpu` or `wasm`. */
+    readonly executionProvider: string;
+}
+/** The fields a qualification record must carry. */
+export declare const QUALIFICATION_FIELDS: readonly (keyof QualificationRecord)[];
+/**
+ * Report which qualification fields are missing (MODEL-05).
+ *
+ * A platform table, a successful package import or a runnable base model is not proof of
+ * correct inference, so a record with gaps is not a qualification however well it runs.
+ * @param record - the partial record.
+ * @returns the missing fields.
+ */
+export declare function qualificationGaps(record: Partial<QualificationRecord>): readonly (keyof QualificationRecord)[];
+/**
+ * Whether a record qualifies a path (MODEL-05).
+ * @param record - the partial record.
+ * @returns whether every required field is present.
+ */
+export declare function isQualified(record: Partial<QualificationRecord>): record is QualificationRecord;
+/** What a model supports, and what an adapter supports. */
+export interface ModalityClaim {
+    readonly modelSupports: readonly Modality[];
+    readonly adapterSupports: readonly Modality[];
+}
+/**
+ * The capabilities that may be ADVERTISED (MODEL-05).
+ *
+ * The intersection, because a model can support a modality while the selected adapter
+ * does not. Advertising the model's list would promise something the adapter cannot do.
+ * @param claim - what each side supports.
+ * @returns the advertisable modalities.
+ */
+export declare function advertisableModalities(claim: ModalityClaim): readonly Modality[];
+/**
+ * Describe a model's capability as the INTERSECTION (MODEL-05).
+ *
+ * The description names what is not advertisable and why, so a reader is not left to
+ * infer that the model lacks the modality when in fact the adapter does.
+ * @param claim - what each side supports.
+ * @returns a description that is true of the pairing.
+ */
+export declare function describeCapability(claim: ModalityClaim): string;
+/**
+ * Resolve one capability (MODEL-06).
+ *
+ * A capability is resolved from what was EVALUATED. A model name is never consulted,
+ * because a brand is not a capability test, and an unevaluated capability returns
+ * `unknown` rather than being inferred from a sibling.
+ * @param evidence - the observed result, or undefined when not evaluated.
+ * @returns the state.
+ */
+export declare function resolveCapability(evidence: boolean | undefined): CapabilityState;
+/**
+ * Whether a model name may be used to infer a capability (MODEL-06).
+ *
+ * It may not. Returns false so the prohibition is asserted rather than merely intended:
+ * a rule that lives only in a comment is one a future branch will not read.
+ * @returns always false.
+ */
+export declare function modelNameImpliesCapability(): boolean;
+/** How a candidate implementation executes (MODEL-04). */
+export type ExecutionMode = 
+/** Pure JavaScript or WASM usable in plain Node. */
+'js-wasm-node'
+/** Prebuilt ONNX Runtime for Node. */
+ | 'onnxruntime-node'
+/** A managed native Windows executable with pinned assets. */
+ | 'managed-native-windows'
+/** Requires Python on the end user's machine. */
+ | 'python-required'
+/** Requires WSL. */
+ | 'wsl-required'
+/** Requires Docker. */
+ | 'docker-required'
+/** Requires a GPU. */
+ | 'gpu-required'
+/** Only works in a browser. */
+ | 'browser-only'
+/** Requires a consumer-side compile step. */
+ | 'consumer-compile';
+/** Why a mode was refused. */
+export interface ModeVerdict {
+    readonly acceptable: boolean;
+    readonly reason?: string;
+}
+/**
+ * Whether an execution mode is acceptable for the end user (MODEL-04).
+ *
+ * Python, WSL, Docker, a GPU and a consumer compile step are all refused: maintainers may
+ * use Python to export artifacts, but it MUST NOT be required on an end user's Windows
+ * machine. A browser-only API does not establish Node support.
+ * @param mode - the mode.
+ * @returns the verdict, with a reason when refused.
+ */
+export declare function executionModeVerdict(mode: ExecutionMode): ModeVerdict;
+/** An embedding space identity (MODEL-01, BASE-12). */
+export interface EmbeddingSpace {
+    /** The model that produces it. */
+    readonly modelId: string;
+    /** The dimensionality of the vectors it produces. */
+    readonly dimensions: number;
+}
+/**
+ * Whether one embedding space may silently stand in for another (BASE-12).
+ *
+ * Only when the dimensions MATCH. EmbeddingGemma 2 is 768-dimensional and MiniLM is
+ * 384-dimensional, so substituting one for the other silently would compare vectors of
+ * different widths and produce meaningless similarity.
+ * @param from - the space in use.
+ * @param to - the proposed replacement.
+ * @returns whether the substitution is safe without an explicit migration.
+ */
+export declare function maySubstituteSilently(from: EmbeddingSpace, to: EmbeddingSpace): boolean;
+/**
+ * Describe an embedding substitution (BASE-12).
+ * @param from - the space in use.
+ * @param to - the proposed replacement.
+ * @returns a description naming the incompatibility when there is one.
+ */
+export declare function describeSubstitution(from: EmbeddingSpace, to: EmbeddingSpace): string;
+/**
+ * The reduced dimensionalities EmbeddingGemma 2 supports (MODEL-01).
+ *
+ * The model card describes 768 reducible to 512, 256 and 128. Recorded rather than
+ * assumed, because a reduction that is not applied consistently produces vectors that
+ * cannot be compared with each other.
+ */
+export declare const EMBEDDINGGEMMA2_DIMENSIONS: readonly number[];
+/**
+ * Whether a stated dimensionality is one EmbeddingGemma 2 can produce (MODEL-01).
+ * @param dimensions - the stated width.
+ * @returns whether it is a documented width.
+ */
+export declare function isEmbeddingGemma2Width(dimensions: number): boolean;
+//# sourceMappingURL=model-qualification.d.ts.map

package/lib/model-qualification.d.ts.map

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

package/lib/model-qualification.js

@@ -0,0 +1,178 @@
+/**
+ * Model qualification and capability resolution (MODEL-01, MODEL-04, MODEL-05, MODEL-06).
+ *
+ * Four rules, each guarding a way of claiming more than is known:
+ *
+ * - **A platform table is not proof of correct inference** (MODEL-05). A record is
+ *   qualified only when the exact revision, artifact hash, tokenizer, processor, engine
+ *   version, ABI and execution provider are all recorded. A missing field is a GAP, and
+ *   a gap is not a qualification.
+ * - **A model's modality list is not an adapter's** (MODEL-05). A model can support
+ *   video while the selected adapter does not, so what is ADVERTISED is the INTERSECTION
+ *   of the two, described as such.
+ * - **A model name is not a capability test** (MODEL-06). Capability comes from the
+ *   resolved model, never from recognising a brand.
+ * - **Unknown is not unsupported** (MODEL-06). The requirement says to record them
+ *   separately, because collapsing them lets an unevaluated capability be reported as a
+ *   known absence — or, worse, the reverse.
+ *
+ * @module @try-works/dsh-tool-mode/model-qualification
+ */
+/** The fields a qualification record must carry. */
+export const QUALIFICATION_FIELDS = [
+    'modelRevision', 'artifactSha', 'tokenizer', 'processor',
+    'engineVersion', 'nodeAbi', 'architecture', 'executionProvider',
+];
+/**
+ * Report which qualification fields are missing (MODEL-05).
+ *
+ * A platform table, a successful package import or a runnable base model is not proof of
+ * correct inference, so a record with gaps is not a qualification however well it runs.
+ * @param record - the partial record.
+ * @returns the missing fields.
+ */
+export function qualificationGaps(record) {
+    return QUALIFICATION_FIELDS.filter(field => {
+        const value = record[field];
+        return typeof value !== 'string' || value.length === 0;
+    });
+}
+/**
+ * Whether a record qualifies a path (MODEL-05).
+ * @param record - the partial record.
+ * @returns whether every required field is present.
+ */
+export function isQualified(record) {
+    return qualificationGaps(record).length === 0;
+}
+/**
+ * The capabilities that may be ADVERTISED (MODEL-05).
+ *
+ * The intersection, because a model can support a modality while the selected adapter
+ * does not. Advertising the model's list would promise something the adapter cannot do.
+ * @param claim - what each side supports.
+ * @returns the advertisable modalities.
+ */
+export function advertisableModalities(claim) {
+    const adapter = new Set(claim.adapterSupports);
+    return claim.modelSupports.filter(modality => adapter.has(modality));
+}
+/**
+ * Describe a model's capability as the INTERSECTION (MODEL-05).
+ *
+ * The description names what is not advertisable and why, so a reader is not left to
+ * infer that the model lacks the modality when in fact the adapter does.
+ * @param claim - what each side supports.
+ * @returns a description that is true of the pairing.
+ */
+export function describeCapability(claim) {
+    const advertisable = advertisableModalities(claim);
+    const adapter = new Set(claim.adapterSupports);
+    // Named rather than omitted: the model supports these, this adapter does not.
+    const modelOnly = claim.modelSupports.filter(modality => !adapter.has(modality));
+    const base = advertisable.length === 0
+        ? 'no modality is advertisable through this adapter'
+        : `advertisable: ${advertisable.join(', ')}`;
+    return modelOnly.length === 0
+        ? base
+        : `${base} (the model also supports ${modelOnly.join(', ')}, which this adapter does not)`;
+}
+/**
+ * Resolve one capability (MODEL-06).
+ *
+ * A capability is resolved from what was EVALUATED. A model name is never consulted,
+ * because a brand is not a capability test, and an unevaluated capability returns
+ * `unknown` rather than being inferred from a sibling.
+ * @param evidence - the observed result, or undefined when not evaluated.
+ * @returns the state.
+ */
+export function resolveCapability(evidence) {
+    if (evidence === undefined)
+        return 'unknown';
+    return evidence ? 'supported' : 'unsupported';
+}
+/**
+ * Whether a model name may be used to infer a capability (MODEL-06).
+ *
+ * It may not. Returns false so the prohibition is asserted rather than merely intended:
+ * a rule that lives only in a comment is one a future branch will not read.
+ * @returns always false.
+ */
+export function modelNameImpliesCapability() {
+    return false;
+}
+/**
+ * Whether an execution mode is acceptable for the end user (MODEL-04).
+ *
+ * Python, WSL, Docker, a GPU and a consumer compile step are all refused: maintainers may
+ * use Python to export artifacts, but it MUST NOT be required on an end user's Windows
+ * machine. A browser-only API does not establish Node support.
+ * @param mode - the mode.
+ * @returns the verdict, with a reason when refused.
+ */
+export function executionModeVerdict(mode) {
+    switch (mode) {
+        case 'js-wasm-node':
+        case 'onnxruntime-node':
+        case 'managed-native-windows':
+            return { acceptable: true };
+        case 'python-required':
+            return {
+                acceptable: false,
+                reason: 'Python may be used by maintainers to export and verify artifacts, but must not be required on an end user machine',
+            };
+        case 'wsl-required':
+            return { acceptable: false, reason: 'WSL must not be required on an end user machine' };
+        case 'docker-required':
+            return { acceptable: false, reason: 'Docker must not be required on an end user machine' };
+        case 'gpu-required':
+            return { acceptable: false, reason: 'no GPU requirement is permitted' };
+        case 'browser-only':
+            return { acceptable: false, reason: 'browser-only APIs do not establish Node support' };
+        case 'consumer-compile':
+            return { acceptable: false, reason: 'no consumer-side compile is permitted' };
+    }
+}
+/**
+ * Whether one embedding space may silently stand in for another (BASE-12).
+ *
+ * Only when the dimensions MATCH. EmbeddingGemma 2 is 768-dimensional and MiniLM is
+ * 384-dimensional, so substituting one for the other silently would compare vectors of
+ * different widths and produce meaningless similarity.
+ * @param from - the space in use.
+ * @param to - the proposed replacement.
+ * @returns whether the substitution is safe without an explicit migration.
+ */
+export function maySubstituteSilently(from, to) {
+    return from.dimensions === to.dimensions;
+}
+/**
+ * Describe an embedding substitution (BASE-12).
+ * @param from - the space in use.
+ * @param to - the proposed replacement.
+ * @returns a description naming the incompatibility when there is one.
+ */
+export function describeSubstitution(from, to) {
+    if (maySubstituteSilently(from, to)) {
+        return `${to.modelId} produces ${to.dimensions}-dimensional vectors, matching ${from.modelId}`;
+    }
+    return `${to.modelId} produces ${to.dimensions}-dimensional vectors and ${from.modelId} produces `
+        + `${from.dimensions}; existing vectors are not comparable and require an explicit re-index`;
+}
+/**
+ * The reduced dimensionalities EmbeddingGemma 2 supports (MODEL-01).
+ *
+ * The model card describes 768 reducible to 512, 256 and 128. Recorded rather than
+ * assumed, because a reduction that is not applied consistently produces vectors that
+ * cannot be compared with each other.
+ */
+export const EMBEDDINGGEMMA2_DIMENSIONS = [768, 512, 256, 128];
+/**
+ * Whether a stated dimensionality is one EmbeddingGemma 2 can produce (MODEL-01).
+ * @param dimensions - the stated width.
+ * @returns whether it is a documented width.
+ */
+export function isEmbeddingGemma2Width(dimensions) {
+    return EMBEDDINGGEMMA2_DIMENSIONS.includes(dimensions);
+}
+//# sourceMappingURL=model-qualification.js.map

package/lib/model-runtime-lane.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The host lane that turns a parsed `model-runtime` recipe into a callable tool
+ * (docs/runtime/PHASE2.md § Host lane).
+ *
+ * WHAT THIS MODULE OWNS, and what it deliberately does not:
+ *
+ * - It owns the CONTRACT between the recipe and DSH: the tool's name and description, the
+ *   projection of the recipe's JSON-Schema input into what DSH can advertise, the FULL
+ *   schema enforced at call time (the projection is intentionally looser), and the output
+ *   check that stops a malformed payload from being published as a result.
+ * - It does NOT own the engine. The provider is a `ModelProviderV1` created by the factory
+ *   the recipe names, which was resolved from the extension's own package (AT-25).
+ *
+ * TIMING IS PART OF THE DESIGN. Creating a tool resolves the provider module but does not
+ * import or run it; the import and the provider's `load` happen on the FIRST CALL. That keeps
+ * activation lightweight (EXT-19) while still refusing — at registration — a package whose
+ * engine is not installed, because resolution is synchronous.
+ *
+ * @module @try-works/dsh-tool-mode/model-runtime-lane
+ */
+import type { InvocationContextV1, PreparedAssetMapV1 } from '@try-works/tool-mode-extension-sdk';
+import { type ModelRuntimeRecipe, type ModelRuntimeRefusal } from './model-runtime-recipe.ts';
+/** What the host hands the lane when it registers one implementation's tool. */
+export interface ModelRuntimeToolDeps {
+    /** The extension that owns the tool, for diagnostics. */
+    readonly extensionId: string;
+    /** The implementation id the recipe belongs to (the manifest's, not the tool name). */
+    readonly implementationId: string;
+    /** The installed package directory. */
+    readonly installPath: string;
+    /** The parsed recipe. */
+    readonly recipe: ModelRuntimeRecipe;
+    /** The host-verified prepared assets for this extension; empty until prepared. */
+    readonly assets: () => Readonly<PreparedAssetMapV1>;
+    /** Build the call-scoped context the SDK contract requires. */
+    readonly invocationContext: (exec: {
+        readonly signal?: AbortSignal;
+    } | undefined) => InvocationContextV1;
+    /** Record a teardown failure without throwing out of a disposer. */
+    readonly onError?: (message: string) => void;
+}
+/** A registered tool's host-side half: what DSH advertises and what it runs. */
+export interface ModelRuntimeToolHandle {
+    readonly name: string;
+    readonly description: string;
+    /** The DSH-advertisable parameters projected from the recipe's input schema. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+    /** The recipe's own input schema, for the MCP advertisement (enforced in full above). */
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    /** The recipe's own output schema, for the MCP advertisement. */
+    readonly outputSchema: Readonly<Record<string, unknown>>;
+    readonly execute: (args: unknown, exec?: {
+        readonly signal?: AbortSignal;
+    }) => Promise<unknown>;
+    readonly dispose: () => Promise<void>;
+}
+/** The lane's outcome: a tool, or a named refusal the host turns into a refusal at registration. */
+export type ModelRuntimeToolResult = {
+    readonly ok: true;
+    readonly tool: ModelRuntimeToolHandle;
+} | ModelRuntimeRefusal;
+/**
+ * Build the tool for one model-runtime implementation.
+ *
+ * @param deps - the installed package, the parsed recipe and the host's context/asset hooks.
+ * @returns the tool handle or a named refusal.
+ */
+export declare function createModelRuntimeTool(deps: ModelRuntimeToolDeps): ModelRuntimeToolResult;
+//# sourceMappingURL=model-runtime-lane.d.ts.map

package/lib/model-runtime-lane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-runtime-lane.d.ts","sourceRoot":"","sources":["../src/model-runtime-lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAA+B,kBAAkB,EAAE,MAAM,oCAAoC,CAAA;AAE9H,OAAO,EAIL,KAAK,kBAAkB,EAEvB,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAA;AAElC,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,QAAQ,CAAC,kBAAkB,CAAC,CAAA;IACnD,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,SAAS,KAAK,mBAAmB,CAAA;IACxG,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7C;AAED,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACtD,yFAAyF;IACzF,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACvD,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACxD,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/F,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAED,oGAAoG;AACpG,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,GAC5D,mBAAmB,CAAA;AASvB;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,sBAAsB,CAkFzF"}