@try-works/dsh-model-as-tool 0.1.3 → 0.4.0

package/lib/harness-llm.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The HOST-side injection seam for the DSH-backed harness provider (HLM-01/02/03).
+ *
+ * The recipes package ships {@link DshLlmProvider} — a REAL `LlmProvider` over the DSH
+ * harness's own LLM surface (`ctx.llm`), with capabilities read from the model's own
+ * descriptor and images transported through a deployment-supplied hook. What the host
+ * adds here is the COMPOSITION, and it is deliberately narrow:
+ *
+ * - the surface is reached STRUCTURALLY, so the host never imports the DSH packages at
+ *   this boundary (they are the deployment's peers, and this module reads exactly the
+ *   two members the adapter consumes);
+ * - the image transport is minted ONLY when the deployment can actually reach the DSH
+ *   attachment service (`ctx.attachments.saveImage`): without it the provider is built
+ *   WITHOUT the hook, so an image-capable model honestly reports `images: 'unknown'`
+ *   and the broker refuses image recipes with EXECUTOR_CAPABILITY_UNKNOWN — never a
+ *   silent drop (HLM-11);
+ * - every failure fails CLOSED: an unreachable surface, a descriptor that cannot be
+ *   resolved, or a descriptor naming another route yields `undefined` plus a diagnostic,
+ *   so the deployment runs as if the option were absent rather than half-wired.
+ *
+ * @module @try-works/dsh-model-as-tool/harness-llm
+ */
+import { type LlmProvider } from '@try-works/tool-mode-recipes';
+/** The opt-in configuration naming one DSH provider route and model. */
+export interface HarnessModelConfig {
+    /** The registered adapter route, e.g. `deepseek`. */
+    readonly provider: string;
+    /** The exact model id, e.g. `deepseek-chat`. */
+    readonly model: string;
+}
+/** One discovered default route/model (the AUTO step's product). */
+export interface HarnessModelDiscovery {
+    readonly provider: string;
+    readonly model: string;
+}
+/**
+ * Discover the deployment's default/selected model for the AUTO composition
+ * (task-93 + task-97). DEFAULT-SAFE: any ambiguity or malformed entry yields
+ * `undefined` — never a guessed route.
+ *
+ * Probes, in order:
+ * 1. the settings service's `describe()` descriptor list: the descriptor whose
+ *    `ns` is `agent-default-model` (the live web profile's settings namespace),
+ *    with the resolved `{provider, model}` read from its `value` — the actual
+ *    SettingsForms API (there is no synchronous `get(ns)`, which was live bug
+ *    #2);
+ * 2. the root config's `model.default` as the `provider/model` string.
+ * @param ctx - the surfaces to probe, read structurally.
+ * @returns the discovered route/model, or undefined when none is unambiguous.
+ */
+export declare function discoverDefaultHarnessModel(ctx: {
+    readonly settings?: unknown;
+    readonly config?: {
+        readonly model?: {
+            readonly default?: unknown;
+        };
+    };
+}): HarnessModelDiscovery | undefined;
+/** The attachment-minting surface `ctx.attachments` satisfies structurally. */
+interface DshAttachmentsSurface {
+    saveImage(input: {
+        readonly data: Uint8Array;
+        readonly mediaType: string;
+    }): Promise<unknown>;
+}
+/**
+ * The LlmRuntime contract the AUTO composition resolves through (read from
+ * D:\deepseek-harness\packages\llm\llm\lib\types\index.d.ts):
+ * - `resolveModelInfo(provider, model)` keys on the REGISTERED ROUTE id
+ *   (LlmRuntime.resolveModelInfo → registration(provider) → the adapter),
+ * - `listProviders(): LlmProviderInfo[]` (sync) — the registered routes,
+ * - `listConfigurableProviders(): LlmConfigurableProvider[]` (sync) — the
+ *   directory mapping a settings namespace to the route it activates
+ *   (`{provider, displayName, settingsNs, settingsPath}`),
+ * - `listModels(provider): Promise<LlmModelInfo[]>` — the per-route catalog.
+ */
+export interface HarnessLlmRuntimeSurface {
+    resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<unknown>;
+    listProviders?(): readonly {
+        id: string;
+        name: string;
+    }[];
+    listConfigurableProviders?(): readonly {
+        provider: string;
+        displayName: string;
+        settingsNs?: string;
+        settingsPath?: readonly string[];
+    }[];
+    listModels?(provider: string): Promise<readonly {
+        provider?: string;
+        id: string;
+        name: string;
+    }[]>;
+}
+/** One resolution outcome (task-98): the runnable pair, or the exact refusal. */
+export type HarnessModelResolution = {
+    readonly ok: true;
+    readonly route: string;
+    readonly model: string;
+} | {
+    readonly ok: false;
+    readonly kind: 'not-ready-yet' | 'not-configured';
+    readonly reason: string;
+};
+/**
+ * Resolve a RUNNABLE (route, model) pair the way the runtime does (task-98):
+ * the configured provider may be a settings namespace or display name rather
+ * than the registered ROUTE id, so a direct resolveModelInfo failure is not
+ * 'not configured' — the runtime's own listings map the configured provider to
+ * its route and confirm the model through the route's catalog. An EMPTY route
+ * registry is 'not ready yet' (the adapter plugins register after this plugin
+ * in the composition order), which is retryable — never locked in as 'none'.
+ * @param llm - the LLM surface, read structurally (the listings are optional).
+ * @param desired - the configured provider/model (the agent-default-model pair).
+ * @param log - the diagnostic sink.
+ * @returns the runnable pair, or the exact not-ready-yet/not-configured reason.
+ */
+export declare function resolveRunnableHarnessModel(llm: HarnessLlmRuntimeSurface, desired: {
+    readonly provider: string;
+    readonly model: string;
+}, log?: (message: string) => void): Promise<HarnessModelResolution>;
+/**
+ * Build the DSH-backed harness provider for one opt-in route/model.
+ *
+ * DEFAULT OFF: this runs only when the operator set {@link HarnessModelConfig}, and it
+ * returns `undefined` (with a diagnostic) whenever the DSH surface cannot actually
+ * serve the named model.
+ * @param ctx - the host context, read structurally.
+ * @param config - the operator's provider/model selection.
+ * @param log - a diagnostic sink for the fail-closed reasons.
+ * @returns the provider, or undefined when the deployment cannot build one.
+ */
+export declare function buildHarnessLlmProvider(ctx: {
+    readonly llm?: unknown;
+    readonly attachments?: DshAttachmentsSurface;
+}, config: HarnessModelConfig, log?: (message: string) => void): Promise<LlmProvider | undefined>;
+export {};
+//# sourceMappingURL=harness-llm.d.ts.map

package/lib/harness-llm.d.ts.map

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

package/lib/harness-llm.js

@@ -0,0 +1,218 @@
+/**
+ * The HOST-side injection seam for the DSH-backed harness provider (HLM-01/02/03).
+ *
+ * The recipes package ships {@link DshLlmProvider} — a REAL `LlmProvider` over the DSH
+ * harness's own LLM surface (`ctx.llm`), with capabilities read from the model's own
+ * descriptor and images transported through a deployment-supplied hook. What the host
+ * adds here is the COMPOSITION, and it is deliberately narrow:
+ *
+ * - the surface is reached STRUCTURALLY, so the host never imports the DSH packages at
+ *   this boundary (they are the deployment's peers, and this module reads exactly the
+ *   two members the adapter consumes);
+ * - the image transport is minted ONLY when the deployment can actually reach the DSH
+ *   attachment service (`ctx.attachments.saveImage`): without it the provider is built
+ *   WITHOUT the hook, so an image-capable model honestly reports `images: 'unknown'`
+ *   and the broker refuses image recipes with EXECUTOR_CAPABILITY_UNKNOWN — never a
+ *   silent drop (HLM-11);
+ * - every failure fails CLOSED: an unreachable surface, a descriptor that cannot be
+ *   resolved, or a descriptor naming another route yields `undefined` plus a diagnostic,
+ *   so the deployment runs as if the option were absent rather than half-wired.
+ *
+ * @module @try-works/dsh-model-as-tool/harness-llm
+ */
+import { DshLlmProvider } from '@try-works/tool-mode-recipes';
+/**
+ * Discover the deployment's default/selected model for the AUTO composition
+ * (task-93 + task-97). DEFAULT-SAFE: any ambiguity or malformed entry yields
+ * `undefined` — never a guessed route.
+ *
+ * Probes, in order:
+ * 1. the settings service's `describe()` descriptor list: the descriptor whose
+ *    `ns` is `agent-default-model` (the live web profile's settings namespace),
+ *    with the resolved `{provider, model}` read from its `value` — the actual
+ *    SettingsForms API (there is no synchronous `get(ns)`, which was live bug
+ *    #2);
+ * 2. the root config's `model.default` as the `provider/model` string.
+ * @param ctx - the surfaces to probe, read structurally.
+ * @returns the discovered route/model, or undefined when none is unambiguous.
+ */
+export function discoverDefaultHarnessModel(ctx) {
+    // 1. The agent-default-model settings descriptor (what the Web composer
+    //    writes into the profile patch; its ns is 'agent-default-model').
+    const settings = ctx.settings;
+    const described = settings?.describe?.();
+    if (Array.isArray(described)) {
+        for (const descriptor of described) {
+            if (descriptor === null || typeof descriptor !== 'object')
+                continue;
+            const entry = descriptor;
+            if (entry.ns !== 'agent-default-model')
+                continue;
+            const value = entry.value;
+            if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                const resolved = value;
+                const provider = resolved['provider'];
+                const model = resolved['model'];
+                if (typeof provider === 'string' && provider.length > 0 && typeof model === 'string' && model.length > 0) {
+                    return { provider, model };
+                }
+            }
+            // The matching descriptor carries no unambiguous pair: refuse rather
+            // than continue probing a malformed entry.
+            return undefined;
+        }
+    }
+    // 2. The root config's model.default, the `provider/model` string.
+    const declared = ctx.config?.model?.default;
+    if (typeof declared === 'string') {
+        const slash = declared.indexOf('/');
+        if (slash > 0 && slash < declared.length - 1) {
+            return { provider: declared.slice(0, slash), model: declared.slice(slash + 1) };
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve a RUNNABLE (route, model) pair the way the runtime does (task-98):
+ * the configured provider may be a settings namespace or display name rather
+ * than the registered ROUTE id, so a direct resolveModelInfo failure is not
+ * 'not configured' — the runtime's own listings map the configured provider to
+ * its route and confirm the model through the route's catalog. An EMPTY route
+ * registry is 'not ready yet' (the adapter plugins register after this plugin
+ * in the composition order), which is retryable — never locked in as 'none'.
+ * @param llm - the LLM surface, read structurally (the listings are optional).
+ * @param desired - the configured provider/model (the agent-default-model pair).
+ * @param log - the diagnostic sink.
+ * @returns the runnable pair, or the exact not-ready-yet/not-configured reason.
+ */
+export async function resolveRunnableHarnessModel(llm, desired, log = () => { }) {
+    // 1. The direct pair: the config's provider IS the route.
+    try {
+        await llm.resolveModelInfo(desired.provider, desired.model);
+        return { ok: true, route: desired.provider, model: desired.model };
+    }
+    catch (error) {
+        log(`direct ${desired.provider}/${desired.model} does not resolve: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // 2. Map the configured provider to a registered route.
+    const providers = llm.listProviders?.() ?? [];
+    if (providers.length === 0) {
+        return {
+            ok: false,
+            kind: 'not-ready-yet',
+            reason: 'the deployment\'s LLM surface has not registered its provider routes yet; retry once the deployment '
+                + 'finishes starting (this is not a configuration error)',
+        };
+    }
+    const byId = providers.find(entry => entry.id === desired.provider);
+    const byName = providers.find(entry => entry.name === desired.provider);
+    let route = byId?.id ?? byName?.id;
+    const directory = llm.listConfigurableProviders?.() ?? [];
+    if (route === undefined) {
+        const entry = directory.find(candidate => (candidate.provider === desired.provider
+            || candidate.settingsNs === desired.provider
+            || candidate.displayName === desired.provider));
+        route = entry?.provider;
+    }
+    if (route === undefined) {
+        /**
+         * TASK-100: an EMPTY configurable-provider directory means the runtime is
+         * still registering — the adapter routes appear FIRST and the directory
+         * entries land after, so a provider the directory cannot map yet is
+         * not-ready-yet, never a terminal not-configured (the live 0.3.4
+         * regression finalized exactly this too early). The retry keeps polling.
+         */
+        if (directory.length === 0) {
+            return {
+                ok: false,
+                kind: 'not-ready-yet',
+                reason: 'the deployment\'s LLM surface has not registered its provider routes yet; retry once the deployment '
+                    + 'finishes starting (this is not a configuration error)',
+            };
+        }
+        return {
+            ok: false,
+            kind: 'not-configured',
+            reason: `the configured provider ${JSON.stringify(desired.provider)} is not a registered LLM route in this `
+                + 'deployment; set config.harnessModel to a runnable route',
+        };
+    }
+    // 3. Confirm the model through the route's own catalog, then a direct probe.
+    if (llm.listModels !== undefined) {
+        try {
+            const catalog = await llm.listModels(route);
+            if (catalog.some(entry => entry.id === desired.model)) {
+                return { ok: true, route, model: desired.model };
+            }
+            if (catalog.length > 0) {
+                return {
+                    ok: false,
+                    kind: 'not-configured',
+                    reason: `the model ${JSON.stringify(desired.model)} is not served by the ${route} route (its catalog lists `
+                        + `${catalog.map(entry => entry.id).join(', ')}); set config.harnessModel to a served model`,
+                };
+            }
+        }
+        catch (error) {
+            log(`the ${route} catalog could not be listed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    try {
+        await llm.resolveModelInfo(route, desired.model);
+        return { ok: true, route, model: desired.model };
+    }
+    catch {
+        return {
+            ok: false,
+            kind: 'not-configured',
+            reason: `the ${route} route does not serve the model ${JSON.stringify(desired.model)}; set config.harnessModel `
+                + 'to a served model',
+        };
+    }
+}
+/**
+ * Build the DSH-backed harness provider for one opt-in route/model.
+ *
+ * DEFAULT OFF: this runs only when the operator set {@link HarnessModelConfig}, and it
+ * returns `undefined` (with a diagnostic) whenever the DSH surface cannot actually
+ * serve the named model.
+ * @param ctx - the host context, read structurally.
+ * @param config - the operator's provider/model selection.
+ * @param log - a diagnostic sink for the fail-closed reasons.
+ * @returns the provider, or undefined when the deployment cannot build one.
+ */
+export async function buildHarnessLlmProvider(ctx, config, log = () => { }) {
+    if (ctx.llm === undefined) {
+        log('the DSH LLM surface is not mounted in this deployment, so the harness provider is not wired');
+        return undefined;
+    }
+    // HLM-11: the image transport exists only when the attachment service does. Without
+    // it the adapter reports images 'unknown' and the broker refuses rather than drops.
+    const attachments = ctx.attachments;
+    let images;
+    if (attachments !== undefined) {
+        images = async (image) => ({
+            type: 'image',
+            attachment: await attachments.saveImage({ data: image.bytes, mediaType: image.mediaType }),
+        });
+    }
+    else {
+        log('the DSH attachment service is not mounted, so image recipes will refuse with EXECUTOR_CAPABILITY_UNKNOWN');
+    }
+    try {
+        return await DshLlmProvider.create({
+            llm: ctx.llm,
+            provider: config.provider,
+            model: config.model,
+            ...images === undefined ? {} : { images },
+        });
+    }
+    catch (error) {
+        // Fail closed: a descriptor that cannot be resolved (route not registered) or one
+        // naming another model leaves the deployment as if the option were absent.
+        log(`could not build the harness provider for ${config.provider}/${config.model}: `
+            + `${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=harness-llm.js.map

package/lib/harness-serving.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Serving a declarative package's recipes through a deployment-supplied harness provider.
+ *
+ * THE LAST LINK OF SLICE 3, and the reason it is a module rather than a few lines in the host:
+ * this is where a resolved RECIPE becomes a callable TOOL, and the pieces have to be joined in a
+ * specific order for the authorization to mean anything.
+ *
+ * WHAT THIS DELIBERATELY IS NOT. It does not construct an `LlmProvider`. Which model answers a
+ * harness call is a deployment's business, and this plugin holds no model-specific code — that
+ * is an architectural rule the repository enforces with a gate. Instead a deployment SUPPLIES a
+ * provider and this module does the joining: authorize the recipe's tool name, run through the
+ * broker, and refuse honestly when no provider was supplied.
+ *
+ * WHY THE REFUSAL IS STILL THE DEFAULT. A declarative package resolves and its recipes parse,
+ * and without a provider nothing can call a model. Serving the tool anyway would present a tool
+ * that fails at invocation, so the refusal happens at RESOLUTION — where a reader can see why —
+ * rather than at the first call.
+ *
+ * @module @try-works/dsh-model-as-tool/harness-serving
+ */
+import { type BrokerRecord, type LlmProvider } from '@try-works/tool-mode-recipes';
+/** A deployment's harness composition. */
+export interface HarnessComposition {
+    /**
+     * The provider that answers harness calls, supplied by the DEPLOYMENT.
+     *
+     * Absent when a deployment composes none — which is the state this plugin ships in, and the
+     * state the refusal exists for.
+     */
+    readonly provider?: LlmProvider;
+    /**
+     * Where invocation records go.
+     *
+     * The broker REFUSES TO CONSTRUCT without one, because a broker that records nothing cannot be
+     * audited. Making it required here means a caller cannot compose a harness path that silently
+     * reports nothing — the failure is at construction rather than at audit time.
+     */
+    readonly journal: (record: BrokerRecord) => void;
+}
+/**
+ * A harness call the caller CANCELLED.
+ *
+ * Distinct from `HarnessFailedError` on purpose: a caller who walked away is not a malfunction,
+ * and conflating the two makes every cancellation look like a fault. The same discipline the
+ * invocation accounting applies to `cancelled`.
+ */
+export declare class HarnessCancelledError extends Error {
+    readonly toolName: string;
+    readonly reason: string;
+    readonly name = "HarnessCancelledError";
+    constructor(toolName: string, reason: string);
+}
+/**
+ * A harness call that FAILED, carrying the broker's machine-readable code.
+ *
+ * The code is preserved rather than flattened into a message, so a caller branches on the CAUSE
+ * instead of matching prose.
+ */
+export declare class HarnessFailedError extends Error {
+    readonly toolName: string;
+    readonly code: string;
+    readonly reason: string;
+    readonly name = "HarnessFailedError";
+    constructor(toolName: string, code: string, reason: string);
+}
+/** A recipe made callable. */
+export interface ServedRecipe {
+    readonly implementationId: string;
+    readonly contractId: string;
+    readonly toolName: string;
+    /** Run the recipe. Throws with the broker's own reason when it cannot. */
+    readonly invoke: (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
+}
+/** The outcome of preparing a declarative package's recipes. */
+export type ServeOutcome = {
+    readonly ok: true;
+    readonly served: readonly ServedRecipe[];
+} | {
+    readonly ok: false;
+    readonly code: 'no-provider' | 'recipe-rejected';
+    readonly detail: string;
+};
+/**
+ * Prepare a declarative package's resolved recipes for serving.
+ *
+ * @param composition - the deployment's harness composition.
+ * @param resolved - the recipes resolved through the convention.
+ * @returns the served recipes, or the reason none can be served.
+ */
+export declare function prepareDeclarative(composition: HarnessComposition, resolved: readonly {
+    readonly id: string;
+    readonly contractId: string;
+    readonly recipe: unknown;
+}[]): ServeOutcome;
+//# sourceMappingURL=harness-serving.d.ts.map

package/lib/harness-serving.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-serving.d.ts","sourceRoot":"","sources":["../src/harness-serving.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,WAAW,EAEjB,MAAM,8BAA8B,CAAA;AAErC,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAA;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;CACjD;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAElC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM;IAD9D,SAAkB,IAAI,2BAA0B;gBAC3B,QAAQ,EAAE,MAAM,EAAW,MAAM,EAAE,MAAM;CAG/D;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAE/B,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM;IADrF,SAAkB,IAAI,wBAAuB;gBACxB,QAAQ,EAAE,MAAM,EAAW,IAAI,EAAE,MAAM,EAAW,MAAM,EAAE,MAAM;CAGtF;AAED,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC3F;AAED,gEAAgE;AAChE,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAErG;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,kBAAkB,EAC/B,QAAQ,EAAE,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,GAClG,YAAY,CA+Fd"}

package/lib/harness-serving.js

@@ -0,0 +1,157 @@
+/**
+ * Serving a declarative package's recipes through a deployment-supplied harness provider.
+ *
+ * THE LAST LINK OF SLICE 3, and the reason it is a module rather than a few lines in the host:
+ * this is where a resolved RECIPE becomes a callable TOOL, and the pieces have to be joined in a
+ * specific order for the authorization to mean anything.
+ *
+ * WHAT THIS DELIBERATELY IS NOT. It does not construct an `LlmProvider`. Which model answers a
+ * harness call is a deployment's business, and this plugin holds no model-specific code — that
+ * is an architectural rule the repository enforces with a gate. Instead a deployment SUPPLIES a
+ * provider and this module does the joining: authorize the recipe's tool name, run through the
+ * broker, and refuse honestly when no provider was supplied.
+ *
+ * WHY THE REFUSAL IS STILL THE DEFAULT. A declarative package resolves and its recipes parse,
+ * and without a provider nothing can call a model. Serving the tool anyway would present a tool
+ * that fails at invocation, so the refusal happens at RESOLUTION — where a reader can see why —
+ * rather than at the first call.
+ *
+ * @module @try-works/dsh-model-as-tool/harness-serving
+ */
+import { HarnessBroker, parseRecipe, } from '@try-works/tool-mode-recipes';
+/**
+ * A harness call the caller CANCELLED.
+ *
+ * Distinct from `HarnessFailedError` on purpose: a caller who walked away is not a malfunction,
+ * and conflating the two makes every cancellation look like a fault. The same discipline the
+ * invocation accounting applies to `cancelled`.
+ */
+export class HarnessCancelledError extends Error {
+    toolName;
+    reason;
+    name = 'HarnessCancelledError';
+    constructor(toolName, reason) {
+        super(`the harness recipe ${toolName} was cancelled: ${reason}`);
+        this.toolName = toolName;
+        this.reason = reason;
+    }
+}
+/**
+ * A harness call that FAILED, carrying the broker's machine-readable code.
+ *
+ * The code is preserved rather than flattened into a message, so a caller branches on the CAUSE
+ * instead of matching prose.
+ */
+export class HarnessFailedError extends Error {
+    toolName;
+    code;
+    reason;
+    name = 'HarnessFailedError';
+    constructor(toolName, code, reason) {
+        super(`the harness recipe ${toolName} failed (${code}): ${reason}`);
+        this.toolName = toolName;
+        this.code = code;
+        this.reason = reason;
+    }
+}
+/**
+ * Prepare a declarative package's resolved recipes for serving.
+ *
+ * @param composition - the deployment's harness composition.
+ * @param resolved - the recipes resolved through the convention.
+ * @returns the served recipes, or the reason none can be served.
+ */
+export function prepareDeclarative(composition, resolved) {
+    /**
+     * NO PROVIDER MEANS NO SERVING, and the refusal names the composition rather than the package.
+     * A reader who is told "the package is declarative" would look in the wrong place: the package
+     * is complete and its recipes resolve.
+     */
+    if (composition.provider === undefined) {
+        return {
+            ok: false,
+            code: 'no-provider',
+            detail: 'this deployment composes no harness LlmProvider, so a declarative package\'s recipes '
+                + 'cannot be executed. The recipes resolved and the broker is available; what is absent '
+                + 'is the provider that would answer a model call.',
+        };
+    }
+    const broker = new HarnessBroker({ record: composition.journal });
+    const served = [];
+    for (const entry of resolved) {
+        /**
+         * THE RECIPE IS VALIDATED HERE, and it previously was not — a HIGH-severity gap found by
+         * adversarial review.
+         *
+         * This line used to be a bare cast: `entry.recipe as RecipeManifest`. The production resolver
+         * hands over raw `JSON.parse` output, so NOTHING validated the file between disk and
+         * execution. The review took `text-title.json` and applied one mutation at a time — an
+         * unexpected `tools` array, a `systemPrompt`, a `${process.env.SECRET_KEY}` interpolation, an
+         * uppercase or path-like tool name, `__proto__`, an absurd `maxOutputTokens`, a missing
+         * `policy`, a missing `inputs`. `parseRecipe` REFUSED ALL TEN; `prepareDeclarative` SERVED ALL
+         * TEN, and they executed. The validator was available and imported by the test that was
+         * supposed to cover this path — and bypassed by the only path that runs a recipe.
+         *
+         * A cast is a claim about a value the compiler cannot check, and here the claim was false for
+         * exactly the inputs an untrusted package would supply.
+         */
+        const parsed = parseRecipe(entry.recipe);
+        if (!parsed.ok) {
+            return {
+                ok: false,
+                code: 'recipe-rejected',
+                detail: `${entry.id}: the recipe did not validate: ${JSON.stringify(parsed).slice(0, 300)}`,
+            };
+        }
+        const recipe = parsed.recipe;
+        /**
+         * AUTHORIZATION IS PER TOOL NAME, and it happens BEFORE anything is served. A recipe whose
+         * name was never authorized must not become callable, or the broker would refuse at
+         * invocation — a failure far from its cause.
+         */
+        const toolName = recipe.tool.name;
+        try {
+            broker.authorize(toolName, composition.provider);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                code: 'recipe-rejected',
+                detail: `${entry.id}: the broker refused to authorize ${toolName}: `
+                    + `${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        served.push({
+            implementationId: entry.id,
+            contractId: entry.contractId,
+            toolName,
+            async invoke(args, signal) {
+                const outcome = await broker.run(recipe, args, signal === undefined ? {} : { signal });
+                if (outcome.kind === 'completed')
+                    return outcome.text;
+                /**
+                 * THE BROKER'S NON-COMPLETED VARIANTS ARE `failed` AND `cancelled` — and an earlier
+                 * version of this comment named `refused`, `truncated` and `tool_call` instead.
+                 *
+                 * Those are variants of `LlmCompletion`, the PROVIDER's reply, not of `BrokerOutcome`,
+                 * what `run` returns. They were plausible and wrong, and the difference is not academic:
+                 * a reader trusting the comment would handle cases that cannot occur here and miss the
+                 * one that can.
+                 *
+                 * CANCELLATION IS NOT A FAILURE, and it used to be thrown as an indistinguishable Error.
+                 * The same discipline applies here as in the invocation accounting: a caller who walked
+                 * away must be able to tell that from a malfunction, or every cancellation inflates the
+                 * error rate. `HarnessCancelledError` exists so it can.
+                 */
+                if (outcome.kind === 'cancelled') {
+                    throw new HarnessCancelledError(toolName, outcome.reason);
+                }
+                // `failed` carries the broker's own machine-readable code, so a caller can branch on the
+                // CAUSE rather than matching on a message.
+                throw new HarnessFailedError(toolName, outcome.code, outcome.reason);
+            },
+        });
+    }
+    return { ok: true, served };
+}
+//# sourceMappingURL=harness-serving.js.map