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

package/lib/index.js

@@ -18,18 +18,41 @@ import { loadCatalog } from "./catalog.js";
 import { resolveCapability } from "./capability.js";
 import { createAdapter } from "./adapters/index.js";
 import { registerModelTool } from "./registrar.js";
+import { registerContractTool } from "./bindings.js";
+import { createGrant } from "./authority.js";
+import { ProviderBridge } from "./provider-bridge.js";
+import { buildSurface } from "./publication.js";
+import { createMcpHost } from "./mcp/host-binding.js";
+import { ToolCallId } from '@deepseek-ai/dsh-llm';
+import { STANDARD_CONTRACTS } from '@try-works/tool-mode-contracts';
 import { renderSkillBody } from "./skills.js";
 import { loadPlaybooks } from "./playbook.js";
 import { commandExists, DEFAULT_CLI_COMMAND } from "./transport.js";
 import { createFileStateStore, createMemoryStateStore, defaultStateFile, resolveSelection, withChoice, } from "./state.js";
 export const name = 'model-tools';
 export const inject = ['tools'];
+/**
+ * This package's version, stamped into every result as `extensionVersion`.
+ * Kept as a literal so the runtime does not depend on reading its own manifest.
+ */
+export /** How many invocation receipts are retained in memory (EXT-35). */ const MAX_RETAINED_RECEIPTS = 200;
+const HOST_VERSION = '0.1.1';
 /** Validate and default the plugin configuration. */
 export const Config = z.object({
     catalogFile: z.string(),
     playbookFile: z.string(),
     stateFile: z.string(),
     persist: z.boolean().default(true),
+    providers: z.dict(z.string()).default({}),
+    legacyAliases: z.boolean().default(false),
+    approvedRoots: z.array(z.string()).default([]),
+    grantId: z.string().default('local-interactive'),
+    recordReceipts: z.boolean().default(true),
+    limits: z.object({
+        maxInputBytes: z.number(),
+        maxAudioSeconds: z.number(),
+        maxResultBytes: z.number(),
+    }),
     models: z.array(z.string()).default([]),
     exclude: z.array(z.string()).default([]),
     exposeUnavailable: z.boolean().default(false),
@@ -107,11 +130,175 @@ export function apply(ctx, config = {}) {
         }),
     }));
     const byId = new Map(resolved.map(item => [item.entry.id, item]));
+    /**
+     * Choose the implementation that serves each standard contract (BASE-02).
+     *
+     * A contract is registered once. Selection is host configuration: an explicit
+     * `providers` override wins only if that model can actually run here, and
+     * otherwise the first eligible implementation in catalog order is used. The
+     * alternatives are kept so discovery can report them without a caller having to
+     * choose a model.
+     */
+    // The host owns provenance and authority: `extension`/`version` name THIS
+    // package, the receipt counter lives here, and the grant is built from operator
+    // configuration, so an implementation can forge neither (BASE-05, DECL-03).
+    let receiptCounter = 0;
+    /** The most recent invocation receipts (EXT-35), bounded so retention cannot grow without limit. */
+    const invocationReceipts = [];
+    const grant = createGrant({
+        grantId: config.grantId ?? 'local-interactive',
+        // Every registered tool is granted to the interactive operator; an external
+        // caller gets a narrower grant of its own rather than reusing this one.
+        allowedTools: [...STANDARD_CONTRACTS.map(contract => contract.toolName), 'model_tools'],
+        approvedRoots: config.approvedRoots ?? [],
+        hostedCode: false,
+        recordingPolicy: config.recordReceipts === false ? 'none' : 'receipts',
+        ...config.limits === undefined ? {} : { limits: config.limits },
+    });
+    const host = {
+        extension: '@try-works/dsh-model-as-tool',
+        extensionVersion: HOST_VERSION,
+        activationGeneration: 1,
+        nextReceiptId: () => `rcpt_${(++receiptCounter).toString(36).padStart(6, '0')}`,
+        grant,
+        callerKind: 'interactive',
+        // EXT-35: bounded in-memory retention. A receipt is provenance, not a log of
+        // content, so retaining the last N costs little and makes the record
+        // recoverable after the call rather than only during it.
+        recordReceipt: receipt => {
+            invocationReceipts.push(receipt);
+            if (invocationReceipts.length > MAX_RETAINED_RECEIPTS)
+                invocationReceipts.shift();
+        },
+    };
+    /**
+     * Extension providers, reached only through the public extension API (BASE-09).
+     *
+     * The host holds no adapter for any model: a catalog entry names the package
+     * that implements it, and this bridge loads it. One bridge per activation, so an
+     * extension serving several models is imported once.
+     */
+    const bridge = new ProviderBridge({
+        grant,
+        activationGeneration: host.activationGeneration,
+        log: (message, fields) => ctx.logger?.debug?.(`[model-as-tool] ${message}`, fields),
+    });
+    const contractById = new Map(STANDARD_CONTRACTS.map(contract => [contract.contract, contract]));
+    const bindings = new Map();
+    for (const contract of STANDARD_CONTRACTS) {
+        const eligible = resolved.filter(item => item.entry.contract === contract.contract && item.verdict.runnable);
+        if (eligible.length === 0)
+            continue;
+        const override = config.providers?.[contract.contract];
+        const chosen = eligible.find(item => item.entry.id === override) ?? eligible[0];
+        if (chosen === undefined)
+            continue;
+        const adapter = createAdapter(chosen.entry, { route: chosen.verdict.route, ...transportOptions }, undefined, bridge);
+        if (adapter === undefined)
+            continue;
+        bindings.set(contract.contract, {
+            contract,
+            implementation: chosen.entry,
+            adapter,
+            route: chosen.verdict.route,
+            alternatives: eligible.filter(item => item.entry.id !== chosen.entry.id).map(item => item.entry.id),
+        });
+    }
+    /** Contracts already registered, so a second implementation joins rather than duplicates. */
+    const registeredContracts = new Map();
+    /**
+     * The MCP surface over the tools this activation actually published (MCP-08/09).
+     *
+     * It reads `registeredContracts`, so a tool appears over MCP only if it was
+     * REGISTERED here — the publication surface already decided that, and re-deriving
+     * it would let MCP advertise something the host had withheld.
+     */
+    const mcpHost = createMcpHost({
+        serverInfo: { name: '@try-works/dsh-model-as-tool', version: HOST_VERSION },
+        surface: {
+            get published() {
+                const out = [];
+                for (const [contractId, registered] of registeredContracts) {
+                    const contract = contractById.get(contractId);
+                    if (contract === undefined)
+                        continue;
+                    out.push({ toolName: registered.toolName, contract });
+                }
+                return out;
+            },
+            async execute({ name, arguments: args, signal, callId }) {
+                // MCP-08: routed through the DSH tool runtime with a SERVER-ISSUED call
+                // identity and the CALLER's signal, never by resolving a definition and
+                // calling it directly — that path would bypass the grant, the receipt and
+                // the result policy the runtime applies.
+                const result = await ctx.tools.execute({
+                    signal,
+                    callId: ToolCallId(callId),
+                    name,
+                    arguments: args,
+                });
+                return result.isError
+                    ? { isError: true, message: result.error.message }
+                    : { isError: false, value: result.value };
+            },
+        },
+        onWithheld: tool => ctx.logger.info(`model-tools: ${tool.toolName} is not exported over MCP: ${tool.notExportableReason ?? 'no reason given'}`),
+    });
+    /**
+     * The publication decision for one catalog entry (EXT-24, EXT-32).
+     *
+     * ONE function decides what may be published, used by the installer and by the
+     * discovery surface. Two call sites computing this separately is how a tool ends
+     * up registered while discovery reports it withheld, or the reverse.
+     */
+    const surfaceFor = (entry) => {
+        const binding = entry.contract === null ? undefined : bindings.get(entry.contract);
+        if (binding === undefined)
+            return undefined;
+        return buildSurface({
+            generation: host.activationGeneration,
+            tools: [{
+                    name: binding.contract.toolName,
+                    contractId: binding.contract.contract,
+                    selectedModelId: binding.implementation.id,
+                    implementations: [
+                        {
+                            extensionId: binding.implementation.provider?.extension
+                                ?? binding.implementation.npmPackage
+                                ?? 'unknown',
+                            modelId: binding.implementation.id,
+                            // There is no preparation lifecycle yet, so a model the capability
+                            // resolver proved runnable is treated as ready. When preparation exists
+                            // this reads the deployment's real readiness instead, and the surface
+                            // already withholds the tool when it is not ready.
+                            readiness: 'ready',
+                            runnable: true,
+                        },
+                        ...binding.alternatives.map(alternativeId => {
+                            // The alternative's own extension, looked up rather than assumed: an
+                            // alternative served by a different package is exactly the case a
+                            // second implementation exists for (EXT-22).
+                            const alternative = resolved.find(item => item.entry.id === alternativeId);
+                            return {
+                                extensionId: alternative?.entry.provider?.extension
+                                    ?? alternative?.entry.npmPackage
+                                    ?? 'unknown',
+                                modelId: alternativeId,
+                                readiness: 'ready',
+                                runnable: true,
+                            };
+                        }),
+                    ],
+                }],
+            skills: [],
+        });
+    };
     /**
      * Register one model's tool and skill.
      *
-     * Idempotent: registering an already-installed model is a no-op, so the
-     * control tool can call it without first checking.
+     * A model bound to a standard contract contributes to that CONTRACT's single
+     * tool; a model with no contract keeps its own per-model tool. Idempotent in
+     * both cases, so the control tool can call it without first checking.
      * @param item - the resolved model to install.
      * @returns whether the model is installed after the call.
      */
@@ -121,14 +308,62 @@ export function apply(ctx, config = {}) {
             return true;
         if (!verdict.runnable && !exposeUnavailable)
             return false;
-        const adapter = createAdapter(entry, { route: verdict.route, ...transportOptions });
-        if (adapter === undefined) {
-            // Runnable but no adapter yet: report rather than register a dead tool.
-            ctx.logger.info(`model-tools: ${entry.name} can run here (${verdict.route}) but no adapter ships yet; skipping ${entry.tool.name}`);
-            return false;
+        let toolName = entry.tool.name;
+        let dispose;
+        if (entry.contract !== null && contractById.has(entry.contract)) {
+            const binding = bindings.get(entry.contract);
+            if (binding === undefined) {
+                // The model implements a contract but lost provider selection, or cannot
+                // run. Report rather than register a second tool for the same contract.
+                ctx.logger.info(`model-tools: ${entry.name} implements ${entry.contract} but is not the selected provider; `
+                    + 'no separate tool is registered (BASE-02)');
+                return false;
+            }
+            /**
+             * EXT-24: decide what may be published BEFORE registering anything.
+             *
+             * The surface is built whole and consulted first, so a tool is registered
+             * only when the surface actually published it. Registering first and
+             * reconciling afterwards is the state EXT-24 forbids: a caller would observe
+             * an available tool whose binding was not yet in place.
+             *
+             * One helper serves the installer and the discovery surface, because two call
+             * sites computing this separately is how a tool gets registered while
+             * discovery reports it withheld, or the reverse.
+             */
+            const surface = surfaceFor(entry);
+            const decision = surface?.tools[0];
+            if (decision === undefined) {
+                const reason = surface?.withheld[0];
+                ctx.logger.info(`model-tools: ${entry.name} is active but its tool is withheld (${reason?.code ?? 'unknown'}): `
+                    + `${reason?.message ?? 'no reason reported'}`);
+                return false;
+            }
+            const existing = registeredContracts.get(entry.contract);
+            if (existing !== undefined) {
+                // Already served by another implementation: this model joins that tool.
+                toolName = existing.toolName;
+                dispose = () => { };
+            }
+            else {
+                const registered = registerContractTool(ctx, binding, host);
+                registeredContracts.set(entry.contract, registered);
+                toolName = registered.toolName;
+                dispose = registered.dispose;
+            }
         }
-        const registration = registerModelTool(ctx, entry, adapter);
-        const record = { ...registration, entry };
+        else {
+            const adapter = createAdapter(entry, { route: verdict.route, ...transportOptions }, undefined, bridge);
+            if (adapter === undefined) {
+                // Runnable but no adapter yet: report rather than register a dead tool.
+                ctx.logger.info(`model-tools: ${entry.name} can run here (${verdict.route}) but no adapter ships yet; skipping ${entry.tool.name}`);
+                return false;
+            }
+            const registration = registerModelTool(ctx, entry, adapter);
+            toolName = registration.toolName;
+            dispose = registration.dispose;
+        }
+        const record = { entry, toolName, dispose };
         if (registerSkills) {
             const skills = ctx.get('skills');
             if (skills !== undefined) {
@@ -142,8 +377,19 @@ export function apply(ctx, config = {}) {
                 });
             }
         }
+        // BASE-03: the deprecated alias is opt-in, so the default catalog shows one
+        // transcription tool. It keeps its own name and adapter, never the new
+        // contract's schema, so an old caller's arguments are not reinterpreted.
+        if (config.legacyAliases === true && entry.contract !== null && entry.tool.name !== toolName) {
+            const aliasAdapter = createAdapter(entry, { route: verdict.route, ...transportOptions }, undefined, bridge);
+            if (aliasAdapter !== undefined) {
+                const alias = registerModelTool(ctx, entry, aliasAdapter);
+                record.disposeAlias = alias.dispose;
+                ctx.logger.info(`model-tools: registered deprecated alias ${alias.toolName} (BASE-03)`);
+            }
+        }
         installed.set(entry.id, record);
-        ctx.logger.info(`model-tools: registered ${entry.tool.name} for ${entry.name} (${verdict.route})`);
+        ctx.logger.info(`model-tools: registered ${toolName} for ${entry.name} (${verdict.route})`);
         return true;
     };
     /**
@@ -156,7 +402,16 @@ export function apply(ctx, config = {}) {
         if (record === undefined)
             return false;
         record.disposeSkill?.();
+        record.disposeAlias?.();
         record.dispose();
+        // A contract-served model's registration is owned by the contract; dropping
+        // the last model that used it must also release the contract's tool, or a
+        // removed implementation would keep answering calls.
+        if (record.entry.contract !== null) {
+            const stillInstalled = [...installed.values()].some(other => other.entry.id !== modelId && other.entry.contract === record.entry.contract);
+            if (!stillInstalled)
+                registeredContracts.delete(record.entry.contract);
+        }
         installed.delete(modelId);
         ctx.logger.info(`model-tools: unregistered ${record.toolName}`);
         return true;
@@ -206,7 +461,7 @@ export function apply(ctx, config = {}) {
                 action: {
                     type: 'string',
                     required: true,
-                    enum: ['list', 'installed', 'describe', 'enable', 'disable', 'reset'],
+                    enum: ['list', 'installed', 'describe', 'enable', 'disable', 'reset', 'receipts', 'mcp'],
                     description: 'list: every catalogued model and whether it runs here. installed: only the models whose tools are '
                         + 'registered. describe: full detail for one model. enable: install a model\'s tool and remember it. '
                         + 'disable: remove a model\'s tool and remember it. reset: forget the remembered choice for one model, '
@@ -251,11 +506,88 @@ export function apply(ctx, config = {}) {
                                     },
                                     license: { type: 'string', required: true },
                                     docs: { type: 'string', required: true },
+                                    /**
+                                     * Public extension/implementation provenance (EXT-32).
+                                     *
+                                     * Declared rather than left open: a discovery surface that could
+                                     * return anything would let the shape drift unnoticed, and the
+                                     * output schema refusing undeclared fields is what caught this
+                                     * addition in the first place.
+                                     */
+                                    provenance: {
+                                        type: 'object',
+                                        additionalProperties: false,
+                                        properties: {
+                                            contract: {
+                                                required: true,
+                                                oneOf: [{ type: 'string' }, { type: 'null' }],
+                                            },
+                                            extension: {
+                                                required: true,
+                                                oneOf: [{ type: 'string' }, { type: 'null' }],
+                                            },
+                                            modelId: {
+                                                required: true,
+                                                oneOf: [{ type: 'string' }, { type: 'null' }],
+                                            },
+                                            publishedTool: {
+                                                required: true,
+                                                oneOf: [{ type: 'string' }, { type: 'null' }],
+                                            },
+                                            alternatives: { type: 'array', required: true, items: { type: 'string' } },
+                                        },
+                                    },
+                                    /** The deployment's readiness, so an absent tool is explicable. */
+                                    readiness: { type: 'string', required: true },
+                                    /** Whether the tool is genuinely callable right now. */
+                                    callable: { type: 'boolean', required: true },
+                                    /** Why the tool is absent, when it is. */
+                                    withheld: {
+                                        type: 'object',
+                                        additionalProperties: false,
+                                        properties: {
+                                            code: { type: 'string', required: true },
+                                            message: { type: 'string', required: true },
+                                        },
+                                    },
                                 },
                             },
                         },
                         installed: { type: 'integer', required: true },
                         runnable: { type: 'integer', required: true },
+                        /** Set by the mcp action: what this host would export over MCP (MCP-09). */
+                        mcp: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                additionalProperties: false,
+                                properties: {
+                                    name: { type: 'string', required: true },
+                                    hasOutputSchema: { type: 'boolean', required: true },
+                                    title: {
+                                        required: true,
+                                        oneOf: [{ type: 'string' }, { type: 'null' }],
+                                    },
+                                },
+                            },
+                        },
+                        /** Set by the receipts action: recent invocation provenance (EXT-35). */
+                        receipts: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                additionalProperties: false,
+                                properties: {
+                                    receiptId: { type: 'string', required: true },
+                                    contract: { type: 'string', required: true },
+                                    implementationId: { type: 'string', required: true },
+                                    extension: { type: 'string', required: true },
+                                    modelIdentity: { type: 'string', required: true },
+                                    activationGeneration: { type: 'integer', required: true },
+                                    executionLocation: { type: 'string', required: true },
+                                },
+                            },
+                        },
                         /** Set by enable/disable/reset: whether the requested change took effect. */
                         changed: { type: 'boolean' },
                         /** Set by enable/disable/reset: what the call did to the tool surface. */
@@ -288,17 +620,92 @@ export function apply(ctx, config = {}) {
                 const modelId = args.model;
                 /** The user's remembered choice for one model. */
                 const choiceOf = (id) => persisted.enabled.includes(id) ? 'enabled' : persisted.disabled.includes(id) ? 'disabled' : 'none';
-                /** The current snapshot, with per-model installed and remembered state. */
-                const snapshot = (items) => items.map(item => ({
-                    ...describeModels([item])[0],
-                    installed: installed.has(item.entry.id),
-                    choice: choiceOf(item.entry.id),
+                /**
+                 * The provenance and readiness a discovery surface must expose (EXT-32).
+                 *
+                 * ALWAYS returns the full shape, including for a model with no contract
+                 * binding: the fields are declared required in the output schema, so a
+                 * partial object would be refused — and a caller reading `readiness` should
+                 * get an answer for every model rather than having to handle its absence.
+                 */
+                const provenanceOf = (entry) => {
+                    const surface = surfaceFor(entry);
+                    const published = surface?.tools[0];
+                    const notice = surface?.readiness.find(item => item.modelId === entry.id);
+                    const withheld = surface === undefined
+                        ? undefined
+                        : surface.withheld.find(item => item.subject === published?.name) ?? surface.withheld[0];
+                    return {
+                        provenance: {
+                            contract: entry.contract,
+                            // Which PACKAGE implements this model, and which model inside it. Read
+                            // from the catalog binding, so it is reported even for a model that is
+                            // not the selected provider and therefore has no published tool.
+                            extension: entry.provider?.extension ?? null,
+                            modelId: entry.provider?.modelId ?? null,
+                            publishedTool: published?.name ?? null,
+                            // Copied into a mutable array: the surface's own list is readonly, and
+                            // a discovery result is a plain JSON value.
+                            alternatives: [...(published?.alternatives ?? [])],
+                        },
+                        readiness: notice?.readiness ?? 'unknown',
+                        callable: notice?.callable ?? false,
+                        ...withheld === undefined ? {} : {
+                            withheld: { code: withheld.code, message: withheld.message },
+                        },
+                    };
+                };
+                /**
+                 * The current snapshot, with per-model installed and remembered state.
+                 *
+                 * `tool` reports the name actually REGISTERED, not the catalog's per-model
+                 * name: under a contract two implementations share one tool, and reporting
+                 * the catalog name would tell a caller to call something that does not exist.
+                 */
+                const snapshot = (items) => items.map(item => {
+                    const record = installed.get(item.entry.id);
+                    return {
+                        ...describeModels([item])[0],
+                        ...record === undefined ? {} : { tool: record.toolName },
+                        ...provenanceOf(item.entry),
+                        installed: record !== undefined,
+                        choice: choiceOf(item.entry.id),
+                    };
+                });
+                /**
+                 * The most recent invocation receipts (EXT-35).
+                 *
+                 * Exposed through discovery so the provenance is observable rather than
+                 * merely recorded: a receipt nobody can read is indistinguishable from no
+                 * receipt at all.
+                 */
+                const receipts = () => invocationReceipts.map(receipt => ({
+                    receiptId: receipt.receiptId,
+                    contract: receipt.contract,
+                    implementationId: receipt.implementationId,
+                    extension: receipt.extension,
+                    modelIdentity: receipt.modelIdentity,
+                    activationGeneration: receipt.activationGeneration,
+                    executionLocation: receipt.executionLocation,
                 }));
                 const counts = () => ({
                     installed: installed.size,
                     runnable: resolved.filter(item => item.verdict.runnable).length,
                     ...persist ? { stateFile: config.stateFile ?? defaultStateFile() } : {},
                 });
+                if (action === 'mcp') {
+                    return { models: [], ...counts(), mcp: mcpHost.listTools().map(tool => ({
+                            name: tool.name,
+                            // Presence of the OUTPUT schema is the MCP-09 fact worth exposing: DSH
+                            // model-facing projection omits it, so this is the evidence that the
+                            // export is built from the contract instead.
+                            hasOutputSchema: tool.outputSchema !== undefined,
+                            title: tool.title ?? null,
+                        })) };
+                }
+                if (action === 'receipts') {
+                    return { models: [], ...counts(), receipts: receipts() };
+                }
                 if (action === 'reset') {
                     // Forgetting a choice is what makes the config authoritative again.
                     if (modelId !== undefined) {
@@ -373,6 +780,7 @@ export function apply(ctx, config = {}) {
     ctx.effect(() => () => {
         for (const record of installed.values()) {
             record.disposeSkill?.();
+            record.disposeAlias?.();
             record.dispose();
         }
         installed.clear();