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

package/lib/licensing.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Licensing, attribution and permission records (LIC-01..LIC-04).
+ *
+ * Two rules here exist to stop a technical decision standing in for a legal one.
+ *
+ * - **A config boolean is not a licence grant** (LIC-03). A person records the
+ *   permission basis, the scope it covers, and their name. Turning on a setting
+ *   cannot produce that record, so the type has no way to express "someone ticked a
+ *   box".
+ * - **Do not describe telemetry-bearing software as network-free** (LIC-04). An
+ *   implementation that must report usage telemetry is INELIGIBLE for a strict
+ *   no-network deployment, and the ineligibility is reported rather than resolved by
+ *   quietly suppressing the telemetry — which would breach the licence and misdescribe
+ *   the product at the same time.
+ *
+ * LIC-01's other half is that the layers are tracked INDEPENDENTLY: an adapter's MIT
+ * licence says nothing about the weights it loads, and a missing layer is a gap rather
+ * than a default.
+ *
+ * @module @try-works/dsh-model-as-tool/licensing
+ */
+/** The layers whose licences are tracked separately (LIC-01). */
+export type LicenseLayer = 
+/** The extension's own source. */
+'code'
+/** The inference engine or runtime. */
+ | 'engine'
+/** The model weights. */
+ | 'weights'
+/** Scripts or tools that converted the weights. */
+ | 'conversion-artifacts'
+/** A vendor SDK the extension depends on. */
+ | 'sdk';
+/** Every layer, so a missing one is detectable rather than absent. */
+export declare const LICENSE_LAYERS: readonly LicenseLayer[];
+/**
+ * Whether redistribution of a layer is permitted.
+ *
+ * `unclear` is a first-class value, because treating an unexamined licence as
+ * permitted is how a package ships bytes it had no right to.
+ */
+export type Redistribution = 'permitted' | 'not-permitted' | 'unclear';
+/** One layer's licence. */
+export interface LayerLicense {
+    readonly layer: LicenseLayer;
+    /** The licence name, e.g. `MIT` or `LicenseRef-DAL-Source-Available-1.0`. */
+    readonly name: string;
+    /** Where the terms live, so a reviewer can read them rather than trust a label. */
+    readonly url: string;
+    /** Whether the licence requires attribution in the product or its notices. */
+    readonly attributionRequired: boolean;
+    /** The exact notice text, when attribution is required. */
+    readonly attributionText?: string;
+    /**
+     * Whether the licence is OSI-approved open source.
+     *
+     * LIC-02 is explicit that Desert Ant's licence is source-available and NOT open
+     * source, so this is recorded per layer rather than inferred from the presence of a
+     * licence file.
+     */
+    readonly openSource: boolean;
+    /** Whether these bytes may be redistributed inside a package. */
+    readonly redistribution: Redistribution;
+    /** Obligations a deployer must meet, stated rather than implied. */
+    readonly obligations: readonly string[];
+}
+/**
+ * The Desert Ant Labs licence, as recorded from the vendor's own terms (LIC-02).
+ *
+ * Named as a constant because getting it wrong in one place is how a wrong belief
+ * spreads: this is source-available, NOT open source, and it forbids redistributing
+ * the models or SDKs as a standalone product.
+ */
+export declare function desertAntLabsLicense(layer: LicenseLayer): LayerLicense;
+/** A resolved licence record for one extension (LIC-01). */
+export interface ResolvedLicenseRecord {
+    readonly extensionId: string;
+    /** One entry per layer. A missing layer is a GAP, not a default. */
+    readonly layers: readonly LayerLicense[];
+    /** Where the notices must appear, kept with the record rather than looked up. */
+    readonly notices: readonly string[];
+}
+/**
+ * Build a licence record, reporting missing layers (LIC-01).
+ *
+ * @param extensionId - the extension.
+ * @param layers - the declared licences.
+ * @returns the record and the layers that were not declared.
+ */
+export declare function resolveLicenses(extensionId: string, layers: readonly LayerLicense[]): {
+    readonly record: ResolvedLicenseRecord;
+    readonly gaps: readonly LicenseLayer[];
+};
+/** The uses a permission basis can cover (LIC-03). */
+export type PermissionScope = 'native' | 'external-export' | 'distribution' | 'telemetry';
+/**
+ * How a permission was established (LIC-03).
+ *
+ * There is deliberately no `config-boolean` member: the requirement says a config
+ * boolean is not a licence grant, and a type that cannot express one is a stronger
+ * guarantee than a comment saying not to use one.
+ */
+export type PermissionBasis = 
+/** The vendor answered the question in writing. */
+{
+    readonly kind: 'vendor-clarification';
+    readonly reference: string;
+}
+/** Qualified review, e.g. counsel, decided the boundary. */
+ | {
+    readonly kind: 'qualified-review';
+    readonly reference: string;
+}
+/** The vendor's own published terms address it directly. */
+ | {
+    readonly kind: 'published-terms';
+    readonly url: string;
+}
+/** A commercial agreement covers it. */
+ | {
+    readonly kind: 'commercial-agreement';
+    readonly reference: string;
+};
+/** A human's record of one permission (LIC-03). */
+export interface PermissionRecord {
+    readonly extensionId: string;
+    readonly scope: PermissionScope;
+    readonly basis: PermissionBasis;
+    /**
+     * The responsible human.
+     *
+     * Required: an unattributed permission record cannot be reviewed or revisited, and
+     * the requirement says a RESPONSIBLE HUMAN must record it.
+     */
+    readonly recordedBy: string;
+    readonly recordedAt: string;
+    /** What the permission does NOT cover, so its limits travel with it. */
+    readonly excludes?: readonly string[];
+}
+/**
+ * Reject a permission claim that is not a human record (LIC-03).
+ *
+ * A boolean, a string or an empty object would all be "someone said yes" without a
+ * person or a reference, which is what the requirement forbids.
+ * @param value - the purported record.
+ * @returns whether it is a usable record.
+ */
+export declare function isUsablePermissionRecord(value: unknown): value is PermissionRecord;
+/**
+ * Whether a provider may be exposed over MCP (LIC-03).
+ *
+ * An unresolved EXTERNAL-EXPORT permission blocks THAT PROVIDER's export and nothing
+ * else. Blocking the whole plugin would punish every other provider for one
+ * unresolved question, which the requirement explicitly rules out.
+ * @param extensionId - the provider.
+ * @param permissions - every recorded permission.
+ * @returns the decision.
+ */
+export declare function exportDecision(extensionId: string, permissions: readonly PermissionRecord[]): {
+    readonly exportable: boolean;
+    readonly reason?: string;
+};
+/** An implementation's network behaviour, as DECLARED rather than assumed (LIC-04). */
+export interface NetworkBehaviour {
+    readonly extensionId: string;
+    /**
+     * Whether the software reports usage telemetry the licence REQUIRES.
+     *
+     * When true, suppressing it to appear network-free would breach the licence, so the
+     * implementation is ineligible for a no-network deployment instead.
+     */
+    readonly requiredTelemetry: boolean;
+    /** Whether it makes any other network call. */
+    readonly otherNetworkUse: boolean;
+    /** What the telemetry carries, so a description can be accurate. */
+    readonly telemetryContent?: readonly string[];
+}
+/** The verdict for a strict no-network deployment (LIC-04). */
+export interface NoNetworkVerdict {
+    readonly eligible: boolean;
+    /** Why not, when it is not. */
+    readonly reason?: string;
+    /** What a deployer should choose instead, rather than a bare refusal. */
+    readonly alternative?: string;
+}
+/**
+ * Decide whether an implementation is eligible for a strict no-network deployment
+ * (LIC-04).
+ *
+ * @param behaviour - the implementation's declared network behaviour.
+ * @returns the verdict, with an alternative when it is ineligible.
+ */
+export declare function noNetworkEligibility(behaviour: NetworkBehaviour): NoNetworkVerdict;
+/**
+ * How a deployment may DESCRIBE itself (LIC-04).
+ *
+ * The requirement forbids describing telemetry-bearing software as entirely
+ * network-free, so a description is derived from the declared behaviour rather than
+ * chosen by the deployer.
+ * @param behaviour - the implementation's network behaviour.
+ * @returns a description that is true of the implementation.
+ */
+export declare function describeNetwork(behaviour: NetworkBehaviour): string;
+/**
+ * Whether packaging a model grants the right to redistribute its weights (LIC-01).
+ *
+ * It does not. Packaging means an adapter plus licensed assets or ACQUISITION
+ * INSTRUCTIONS; technical availability does not imply export or redistribution
+ * permission.
+ * @param record - the licence record.
+ * @returns whether the weights may be shipped inside the package.
+ */
+export declare function mayPackageWeights(record: ResolvedLicenseRecord): boolean;
+/**
+ * Whether the notices required by a record are present in a shipped notice file.
+ * @param record - the licence record.
+ * @param noticeText - the notice file's contents.
+ * @returns the notices that are missing.
+ */
+export declare function missingNotices(record: ResolvedLicenseRecord, noticeText: string): readonly string[];
+//# sourceMappingURL=licensing.d.ts.map

package/lib/licensing.d.ts.map

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

package/lib/licensing.js

@@ -0,0 +1,188 @@
+/**
+ * Licensing, attribution and permission records (LIC-01..LIC-04).
+ *
+ * Two rules here exist to stop a technical decision standing in for a legal one.
+ *
+ * - **A config boolean is not a licence grant** (LIC-03). A person records the
+ *   permission basis, the scope it covers, and their name. Turning on a setting
+ *   cannot produce that record, so the type has no way to express "someone ticked a
+ *   box".
+ * - **Do not describe telemetry-bearing software as network-free** (LIC-04). An
+ *   implementation that must report usage telemetry is INELIGIBLE for a strict
+ *   no-network deployment, and the ineligibility is reported rather than resolved by
+ *   quietly suppressing the telemetry — which would breach the licence and misdescribe
+ *   the product at the same time.
+ *
+ * LIC-01's other half is that the layers are tracked INDEPENDENTLY: an adapter's MIT
+ * licence says nothing about the weights it loads, and a missing layer is a gap rather
+ * than a default.
+ *
+ * @module @try-works/dsh-model-as-tool/licensing
+ */
+/** Every layer, so a missing one is detectable rather than absent. */
+export const LICENSE_LAYERS = [
+    'code', 'engine', 'weights', 'conversion-artifacts', 'sdk',
+];
+/**
+ * The Desert Ant Labs licence, as recorded from the vendor's own terms (LIC-02).
+ *
+ * Named as a constant because getting it wrong in one place is how a wrong belief
+ * spreads: this is source-available, NOT open source, and it forbids redistributing
+ * the models or SDKs as a standalone product.
+ */
+export function desertAntLabsLicense(layer) {
+    return {
+        layer,
+        name: 'Desert Ant Labs Source-Available License 1.0',
+        url: 'https://license.desertant.com/1.0',
+        attributionRequired: true,
+        attributionText: 'Powered by Desert Ant Labs',
+        // LIC-02 says this in as many words.
+        openSource: false,
+        // No redistribution or re-hosting of the models, SDKs or a hosted service.
+        redistribution: 'not-permitted',
+        obligations: [
+            'display the attribution notice with a link to Desert Ant Labs',
+            'a commercial licence is required above the per-platform, per-model active-device threshold',
+            'do not redistribute the model, SDK or a hosted service as a standalone product',
+            'do not use outputs or logs to train a competing on-device model',
+            'do not extract weights or tamper with the usage telemetry',
+        ],
+    };
+}
+/**
+ * Build a licence record, reporting missing layers (LIC-01).
+ *
+ * @param extensionId - the extension.
+ * @param layers - the declared licences.
+ * @returns the record and the layers that were not declared.
+ */
+export function resolveLicenses(extensionId, layers) {
+    const declared = new Set(layers.map(layer => layer.layer));
+    // An undeclared layer is reported rather than assumed permissive: an adapter's MIT
+    // licence says nothing about the weights it loads.
+    const gaps = LICENSE_LAYERS.filter(layer => !declared.has(layer));
+    return {
+        record: {
+            extensionId,
+            layers,
+            // Collected from every layer that requires one, so a notice is never dropped by
+            // being attached to a layer nobody reads.
+            notices: layers
+                .filter(layer => layer.attributionRequired && layer.attributionText !== undefined)
+                .map(layer => layer.attributionText),
+        },
+        gaps,
+    };
+}
+/**
+ * Reject a permission claim that is not a human record (LIC-03).
+ *
+ * A boolean, a string or an empty object would all be "someone said yes" without a
+ * person or a reference, which is what the requirement forbids.
+ * @param value - the purported record.
+ * @returns whether it is a usable record.
+ */
+export function isUsablePermissionRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.extensionId === 'string'
+        && typeof candidate.scope === 'string'
+        && typeof candidate.recordedBy === 'string' && candidate.recordedBy.length > 0
+        && typeof candidate.recordedAt === 'string'
+        && typeof candidate.basis === 'object' && candidate.basis !== null;
+}
+/**
+ * Whether a provider may be exposed over MCP (LIC-03).
+ *
+ * An unresolved EXTERNAL-EXPORT permission blocks THAT PROVIDER's export and nothing
+ * else. Blocking the whole plugin would punish every other provider for one
+ * unresolved question, which the requirement explicitly rules out.
+ * @param extensionId - the provider.
+ * @param permissions - every recorded permission.
+ * @returns the decision.
+ */
+export function exportDecision(extensionId, permissions) {
+    const relevant = permissions.find(record => record.extensionId === extensionId && record.scope === 'external-export');
+    if (relevant === undefined) {
+        return {
+            exportable: false,
+            reason: `no external-export permission is recorded for ${extensionId}; `
+                + 'this blocks that provider only, not the other providers',
+        };
+    }
+    if (!isUsablePermissionRecord(relevant)) {
+        return { exportable: false, reason: `the external-export record for ${extensionId} is not a usable record` };
+    }
+    return { exportable: true };
+}
+/**
+ * Decide whether an implementation is eligible for a strict no-network deployment
+ * (LIC-04).
+ *
+ * @param behaviour - the implementation's declared network behaviour.
+ * @returns the verdict, with an alternative when it is ineligible.
+ */
+export function noNetworkEligibility(behaviour) {
+    if (behaviour.requiredTelemetry) {
+        // The honest outcome. Suppressing the telemetry would breach the licence AND
+        // misdescribe the software, so neither is offered.
+        return {
+            eligible: false,
+            reason: 'this implementation must report usage telemetry, so it cannot be described or deployed as network-free',
+            alternative: 'choose an implementation whose licence requires no telemetry, or run a profile that permits its telemetry',
+        };
+    }
+    if (behaviour.otherNetworkUse) {
+        return {
+            eligible: false,
+            reason: 'this implementation makes network calls unrelated to telemetry',
+            alternative: 'choose a local-only implementation, or run a profile that permits those destinations',
+        };
+    }
+    return { eligible: true };
+}
+/**
+ * How a deployment may DESCRIBE itself (LIC-04).
+ *
+ * The requirement forbids describing telemetry-bearing software as entirely
+ * network-free, so a description is derived from the declared behaviour rather than
+ * chosen by the deployer.
+ * @param behaviour - the implementation's network behaviour.
+ * @returns a description that is true of the implementation.
+ */
+export function describeNetwork(behaviour) {
+    if (behaviour.requiredTelemetry) {
+        const content = behaviour.telemetryContent ?? [];
+        return 'reports usage telemetry'
+            + (content.length > 0 ? ` (${content.join(', ')})` : '')
+            + '; it is not network-free';
+    }
+    return behaviour.otherNetworkUse ? 'makes network calls' : 'runs without network access';
+}
+/**
+ * Whether packaging a model grants the right to redistribute its weights (LIC-01).
+ *
+ * It does not. Packaging means an adapter plus licensed assets or ACQUISITION
+ * INSTRUCTIONS; technical availability does not imply export or redistribution
+ * permission.
+ * @param record - the licence record.
+ * @returns whether the weights may be shipped inside the package.
+ */
+export function mayPackageWeights(record) {
+    const weights = record.layers.find(layer => layer.layer === 'weights');
+    // `unclear` is not permission: treating an unexamined licence as permitted is how a
+    // package ships bytes it had no right to.
+    return weights?.redistribution === 'permitted';
+}
+/**
+ * Whether the notices required by a record are present in a shipped notice file.
+ * @param record - the licence record.
+ * @param noticeText - the notice file's contents.
+ * @returns the notices that are missing.
+ */
+export function missingNotices(record, noticeText) {
+    return record.notices.filter(notice => !noticeText.includes(notice));
+}
+//# sourceMappingURL=licensing.js.map

package/lib/mcp/host-binding.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Binding the MCP surface to the real DSH tool registry (MCP-08, MCP-09, MCP-12).
+ *
+ * Two requirements shape this module, and both are about where data comes from
+ * rather than what it looks like:
+ *
+ * - **MCP-09**: DSH's model-facing `schemas()` projection INTENTIONALLY omits the
+ *   output schema, so an export built from it would publish a tool with no declared
+ *   result shape. The canonical schemas therefore come from the CONTRACTS, which is
+ *   the only place that has them; `schemas()` is never consulted for a schema.
+ * - **MCP-08**: invocation goes through the host's `execute` path with a
+ *   server-issued call identity and the caller's abort signal. Resolving a tool and
+ *   calling it directly would bypass the grant, the receipt and the result policy —
+ *   the three things the host path exists to apply — so this module is given an
+ *   executor rather than a registry to reach into.
+ *
+ * §16.4 defines the payload derivation precisely: an implementation returns the
+ * domain payload with the reserved root `meta` OMITTED, and the payload schema is
+ * the final tool schema with only that property and its required entry removed.
+ * Everything else is preserved, because a schema that quietly dropped more would
+ * under-declare the result.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/host-binding
+ */
+import type { ToolContract } from '@try-works/tool-mode-contracts';
+import type { McpHost } from './server.ts';
+/**
+ * Derive the payload schema from a contract's final output schema (§16.4).
+ *
+ * Only the reserved `meta` property and its `required` entry are removed. The rest
+ * of the schema — including constraints on the remaining properties — is preserved
+ * verbatim, because removing anything else would advertise a looser result than the
+ * contract actually enforces.
+ * @param outputSchema - the contract's output schema, including `meta`.
+ * @returns the payload schema.
+ */
+export declare function derivePayloadSchema(outputSchema: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/** One published tool as the host knows it. */
+export interface PublishedTool {
+    /** The tool name a caller uses. */
+    readonly toolName: string;
+    /** The contract it implements, which carries the canonical schemas. */
+    readonly contract: ToolContract;
+    /**
+     * Why this tool is not exportable, when it is not (MCP-12).
+     *
+     * A host tool using a non-JSON callback, a UI-only API, an unsupported attachment
+     * or a non-exportable policy must be REJECTED WITH A REASON rather than partly
+     * serialized, so the reason travels with the tool instead of being discovered by a
+     * caller whose call fails in a way nobody can explain.
+     */
+    readonly notExportableReason?: string;
+}
+/** What the binding needs from the host. */
+export interface HostSurface {
+    /** The tools the host currently publishes. */
+    readonly published: readonly PublishedTool[];
+    /**
+     * Execute one tool through the host path (MCP-08).
+     *
+     * Takes a server-issued call identity and the caller's signal; the implementation
+     * MUST route this through the same execution path a native call uses.
+     */
+    execute(request: {
+        readonly name: string;
+        readonly arguments: Readonly<Record<string, unknown>>;
+        readonly signal: AbortSignal;
+        /** Server-issued. A caller-supplied id would let a caller forge a receipt. */
+        readonly callId: string;
+    }): Promise<{
+        readonly isError: boolean;
+        readonly value?: unknown;
+        readonly message?: string;
+    }>;
+}
+/**
+ * Build the MCP host surface over a DSH tool surface.
+ *
+ * @param options - the host surface and this server's identity.
+ * @returns the MCP host the dispatch layer consumes.
+ */
+export declare function createMcpHost(options: {
+    readonly surface: HostSurface;
+    readonly serverInfo: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** Called for each tool withheld, so a reason is recorded rather than lost. */
+    readonly onWithheld?: (tool: PublishedTool) => void;
+}): McpHost;
+//# sourceMappingURL=host-binding.d.ts.map

package/lib/mcp/host-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-binding.d.ts","sourceRoot":"","sources":["../../src/mcp/host-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAClE,OAAO,KAAK,EAAE,OAAO,EAA4C,MAAM,aAAa,CAAA;AAKpF;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACtC;AAED,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAA;IAC5C;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;QACrD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;QAC5B,8EAA8E;QAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KACxB,GAAG,OAAO,CAAC;QACV,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;QACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;QACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAC1B,CAAC,CAAA;CACH;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACrC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACxE,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAA;CACpD,GAAG,OAAO,CAqEV"}

package/lib/mcp/host-binding.js

@@ -0,0 +1,133 @@
+/**
+ * Binding the MCP surface to the real DSH tool registry (MCP-08, MCP-09, MCP-12).
+ *
+ * Two requirements shape this module, and both are about where data comes from
+ * rather than what it looks like:
+ *
+ * - **MCP-09**: DSH's model-facing `schemas()` projection INTENTIONALLY omits the
+ *   output schema, so an export built from it would publish a tool with no declared
+ *   result shape. The canonical schemas therefore come from the CONTRACTS, which is
+ *   the only place that has them; `schemas()` is never consulted for a schema.
+ * - **MCP-08**: invocation goes through the host's `execute` path with a
+ *   server-issued call identity and the caller's abort signal. Resolving a tool and
+ *   calling it directly would bypass the grant, the receipt and the result policy —
+ *   the three things the host path exists to apply — so this module is given an
+ *   executor rather than a registry to reach into.
+ *
+ * §16.4 defines the payload derivation precisely: an implementation returns the
+ * domain payload with the reserved root `meta` OMITTED, and the payload schema is
+ * the final tool schema with only that property and its required entry removed.
+ * Everything else is preserved, because a schema that quietly dropped more would
+ * under-declare the result.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/host-binding
+ */
+/** The reserved root field the host authors, never the implementation. */
+const RESERVED_META = 'meta';
+/**
+ * Derive the payload schema from a contract's final output schema (§16.4).
+ *
+ * Only the reserved `meta` property and its `required` entry are removed. The rest
+ * of the schema — including constraints on the remaining properties — is preserved
+ * verbatim, because removing anything else would advertise a looser result than the
+ * contract actually enforces.
+ * @param outputSchema - the contract's output schema, including `meta`.
+ * @returns the payload schema.
+ */
+export function derivePayloadSchema(outputSchema) {
+    const clone = structuredClone(outputSchema);
+    if (typeof clone.properties === 'object' && clone.properties !== null) {
+        delete clone.properties[RESERVED_META];
+    }
+    if (Array.isArray(clone.required)) {
+        clone.required = clone.required.filter(entry => entry !== RESERVED_META);
+    }
+    return clone;
+}
+/**
+ * Build the MCP host surface over a DSH tool surface.
+ *
+ * @param options - the host surface and this server's identity.
+ * @returns the MCP host the dispatch layer consumes.
+ */
+export function createMcpHost(options) {
+    let counter = 0;
+    return {
+        serverInfo: options.serverInfo,
+        listTools() {
+            const out = [];
+            for (const published of options.surface.published) {
+                // MCP-12: a tool that cannot be exported faithfully is withheld entirely,
+                // with its reason recorded. Exporting a partial tool would tell a client the
+                // tool exists and then fail in a way the client cannot interpret.
+                if (published.notExportableReason !== undefined) {
+                    options.onWithheld?.(published);
+                    continue;
+                }
+                out.push({
+                    name: published.toolName,
+                    description: published.contract.description,
+                    // Both schemas come from the CONTRACT. `schemas()` omits output, so using
+                    // it here would publish a tool with no declared result shape (MCP-09).
+                    inputSchema: published.contract.inputSchema,
+                    outputSchema: derivePayloadSchema(published.contract.outputSchema),
+                    // Nothing in this binding imports from another MCP server, so no tool is
+                    // a re-export (MCP-13).
+                    importedFromMcp: false,
+                });
+            }
+            return out;
+        },
+        async callTool(name, args, signal) {
+            const definition = options.surface.published.find(tool => tool.toolName === name);
+            // A tool that is not EXPORTABLE must not be callable either. Looking only for
+            // its presence in `published` would let a client invoke by name exactly the
+            // tool the export deliberately withheld — defeating MCP-12 through the back
+            // door, since a client that guessed the name would get a partial result the
+            // export refused to promise.
+            if (definition === undefined || definition.notExportableReason !== undefined) {
+                return {
+                    structured: null,
+                    text: `unknown tool ${JSON.stringify(name)}`,
+                    isError: true,
+                };
+            }
+            const outcome = await options.surface.execute({
+                name,
+                arguments: args,
+                signal,
+                // Server-issued, monotonically increasing. A caller-supplied identity would
+                // let a caller forge a receipt (BASE-05).
+                callId: `mcp_${Date.now().toString(36)}_${(++counter).toString(36)}`,
+            });
+            if (outcome.isError) {
+                return {
+                    structured: null,
+                    // Bounded by the dispatch layer when it becomes a tool-error result.
+                    text: outcome.message ?? 'the tool failed without reporting a reason',
+                    isError: true,
+                };
+            }
+            return {
+                // The canonical value, post-policy, exactly as the host returned it: a
+                // redaction here would be a content-only control, which MCP-11 says is not a
+                // confidentiality control at all.
+                structured: outcome.value ?? null,
+                text: renderBounded(outcome.value),
+            };
+        },
+    };
+}
+/**
+ * Render a bounded, model-readable representation of a canonical value.
+ *
+ * Bounded because a result is copied into a model's context, and an unbounded
+ * rendering of a large value would consume it silently.
+ * @param value - the canonical value.
+ * @returns the text rendering.
+ */
+function renderBounded(value) {
+    const text = typeof value === 'string' ? value : JSON.stringify(value ?? null);
+    return text.length > 100_000 ? `${text.slice(0, 100_000)}…(truncated)` : text;
+}
+//# sourceMappingURL=host-binding.js.map