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

package/node_modules/@try-works/tool-mode-recipes/lib/broker.js

@@ -0,0 +1,647 @@
+/**
+ * The DSH LLM broker: one provider-neutral harness executor for declarative recipes
+ * (HLM-01, HLM-02, HLM-05, HLM-06, HLM-07, HLM-09, HLM-10, HLM-11).
+ *
+ * The broker's whole job is to build ONE request that contains nothing but the recipe's
+ * instructions and the validated bound inputs, and then to report honestly what came
+ * back. Every invariant here is a way the request could stop being that request, or the
+ * result stop being the result:
+ *
+ * - **The request is isolated by construction.** It is built from the recipe and the
+ *   bound values alone. There is no parameter through which parent history, a parent
+ *   system prompt, a tool catalog, skills, attachments or memory could arrive, and the
+ *   shape is frozen so nothing can be added to it after validation (HLM-05, AT-68).
+ * - **Images are typed media, or the call is refused.** An image recipe on a provider
+ *   whose capabilities do not cover images fails with `IMAGE_INPUT_UNAVAILABLE`. It does
+ *   not quietly degrade to a text-only call that "describes" an image the model never
+ *   received — that fallback produces a fluent invention, which is worse than an error
+ *   (HLM-11).
+ * - **An unknown capability is not permission.** A provider that has not reported its
+ *   image support fails with `EXECUTOR_CAPABILITY_UNKNOWN` rather than being assumed
+ *   capable (MODEL-06's three-state rule, reused here).
+ * - **Remote is a policy decision, not an implementation detail.** `permitsDestination`
+ *   is mirrored from RES-10 so a local-only profile refuses a remote provider however
+ *   the tool was built.
+ * - **Cancellation is reported as cancellation.** An aborted signal can never produce a
+ *   success, and never an empty one: an empty success is exactly what a caller writes
+ *   into a document (HLM-10).
+ * - **Refusal, truncation, an empty completion and a stray tool call are errors, each
+ *   with its own code.** HLM-07 requires them to be distinct failures, because a caller
+ *   that cannot tell "the model refused" from "the model was cut off" cannot respond
+ *   correctly to either (RCP-11).
+ * - **Recording is a precondition, not a side effect.** A recipe that declines recording
+ *   under a host that requires it is refused with `CAPTURE_POLICY_CONFLICT` BEFORE the
+ *   provider is called, because refusing after the call would report a refusal for work
+ *   that has already been billed (HLM-09).
+ *
+ * @module @try-works/tool-mode-recipes/broker
+ */
+import { errorCodeOf, INITIAL_MAX_IMAGE_INPUTS, INITIAL_MAX_OUTPUT_TOKENS, renderPrompt, validateRecipeInputs, } from "./recipe-format.js";
+/**
+ * RCP-11: the complete public vocabulary, exported so a host projects THESE codes
+ * into its own transport instead of inventing or flattening one.
+ */
+export const BROKER_ERROR_CODES = Object.freeze([
+    'EXECUTOR_NOT_CONFIGURED',
+    'EXECUTOR_CAPABILITY_UNKNOWN',
+    'UNSUPPORTED_MODALITY',
+    'IMAGE_INPUT_UNAVAILABLE',
+    'IMAGE_INPUT_INVALID',
+    'CAPTURE_POLICY_CONFLICT',
+    'MODEL_REFUSED',
+    'MODEL_OUTPUT_TRUNCATED',
+    'INVALID_MODEL_OUTPUT',
+    'UNEXPECTED_MODEL_TOOL_CALL',
+    'MODEL_BUDGET_EXCEEDED',
+    'INVALID_RECIPE',
+    'RECIPE_BINDING_ERROR',
+    'CANCELLED',
+    'PROVIDER_FAILED',
+    'RECORDING_FAILED',
+]);
+/**
+ * The initial policy: RES-10's initial per-leaf maxima, with recording required.
+ *
+ * Recording defaults to REQUIRED because HLM-09 makes reconstructability a DSH
+ * requirement, and a default of "off" is how a harness call ends up unrecorded without
+ * anyone deciding that.
+ */
+export const INITIAL_HOST_POLICY = {
+    requireRecording: true,
+    remoteDestinations: true,
+    outputTokens: INITIAL_MAX_OUTPUT_TOKENS,
+    imageInputs: INITIAL_MAX_IMAGE_INPUTS,
+};
+/** A local-only policy, which forbids remote destinations however the tool was built. */
+export const LOCAL_ONLY_HOST_POLICY = {
+    ...INITIAL_HOST_POLICY,
+    remoteDestinations: false,
+};
+/**
+ * Whether a policy permits reaching a destination (RES-10).
+ *
+ * Mirrored from the host's `harness-budgets.permitsDestination`: a local-only profile
+ * prohibits remote destinations INDEPENDENTLY of how the tool was implemented, so this
+ * asks the policy rather than the implementation. `local` is always permitted.
+ * @param policy - the policy in force.
+ * @param destination - the destination being considered.
+ * @returns whether it is permitted.
+ */
+export function permitsDestination(policy, destination) {
+    return destination === 'local' ? true : policy.remoteDestinations;
+}
+/**
+ * Narrow a policy by a requested reduction (RES-10, HLM-07).
+ *
+ * Every figure takes the MINIMUM, so a request can only lower a limit; that direction is
+ * the point, since a caller asking for more than the profile permits must get the
+ * profile's figure. `requireRecording` is an OR: a request can demand recording where
+ * the base was silent, and can never switch it off.
+ * @param base - the policy in force.
+ * @param requested - what the caller asked for.
+ * @returns the effective policy.
+ */
+export function narrowBrokerPolicy(base, requested) {
+    const lower = (a, b) => (b === undefined ? a : Math.min(a, b));
+    return {
+        requireRecording: base.requireRecording || (requested.requireRecording ?? false),
+        // A reduction can never ENABLE remote destinations, so this is an AND.
+        remoteDestinations: base.remoteDestinations && (requested.remoteDestinations ?? true),
+        outputTokens: lower(base.outputTokens, requested.outputTokens),
+        imageInputs: lower(base.imageInputs, requested.imageInputs),
+    };
+}
+/** Raised by {@link HarnessBroker.runOrThrow}. */
+export class BrokerError extends Error {
+    name = 'BrokerError';
+    /** The failure code. */
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+    }
+}
+/** Normalise the two-state shorthand into the three-state capability. */
+function imageCapability(value) {
+    if (value === true)
+        return 'supported';
+    if (value === false)
+        return 'unsupported';
+    return value;
+}
+/** Name a thrown value for a failure reason. */
+function messageOf(error) {
+    try {
+        return error instanceof Error ? error.message : String(error);
+    }
+    catch {
+        return '<unrenderable>';
+    }
+}
+/** The codes a binding error may carry, most specific first in the report. */
+const BINDING_CODES = ['RECIPE_BINDING_ERROR', 'MODEL_BUDGET_EXCEEDED', 'UNSUPPORTED_MODALITY'];
+/**
+ * The code a binding failure reports.
+ *
+ * The individual errors carry their own codes, and collapsing a specific one into a
+ * blanket `RECIPE_BINDING_ERROR` would destroy the distinction RCP-11 exists to keep: a
+ * caller that cannot tell "you sent a PDF where an image belongs" from "you misspelled a
+ * field" cannot respond correctly to either. The first error is used, because that is the
+ * one the caller has to fix first.
+ * @param errors - the rendered binding errors.
+ * @returns the code to report.
+ */
+function bindingCode(errors) {
+    const code = errorCodeOf(errors[0] ?? '');
+    return BINDING_CODES.find(candidate => candidate === code) ?? 'RECIPE_BINDING_ERROR';
+}
+/**
+ * Build the ONE request a recipe can produce (HLM-05).
+ *
+ * Exported because the isolation property deserves to be checkable without a provider:
+ * the request object's key set IS the claim that nothing else is sent.
+ * @param recipe - the recipe being run.
+ * @param values - validated bindings.
+ * @param maxOutputTokens - the effective ceiling.
+ * @param signal - the cancellation channel.
+ * @returns the frozen request.
+ */
+export function buildIsolatedRequest(recipe, values, maxOutputTokens, signal) {
+    const images = imagesOf(recipe, values);
+    return Object.freeze({
+        prompt: renderPrompt(recipe, values),
+        ...(images.length === 0
+            ? {}
+            : { images: Object.freeze(images.map(image => Object.freeze({ mediaType: image.mediaType, bytes: image.bytes }))) }),
+        maxOutputTokens,
+        signal,
+        /*
+         * `system` is absent, and that is the assertion: a recipe in this format cannot
+         * supply a system prompt, and the parent's must not be inherited (HLM-05). A request
+         * with a system member would be one built from something other than the recipe.
+         */
+    });
+}
+/** The bound images of a recipe, in declaration order. */
+function imagesOf(recipe, values) {
+    const images = [];
+    for (const [name, declaration] of Object.entries(recipe.inputs)) {
+        if (declaration.type !== 'image')
+            continue;
+        const value = values[name];
+        if (value !== undefined)
+            images.push(value);
+    }
+    return images;
+}
+/**
+ * The harness broker.
+ *
+ * One instance holds the authorizations (which tool may use which provider generation)
+ * and the host policy. It is deliberately not a registry of tools: nothing here switches
+ * on a tool name, which is what RCP-12 forbids and what the tests assert by running two
+ * different recipes through the same code path.
+ */
+export class HarnessBroker {
+    #grants = new Map();
+    #policy;
+    #record;
+    constructor(options = {}) {
+        this.#policy = options.policy ?? INITIAL_HOST_POLICY;
+        this.#record = options.record;
+        /**
+         * Refuse to exist in a state where recording would be claimed and not performed.
+         *
+         * The alternative — accepting the policy and journaling nothing — is the failure
+         * mode HLM-09 names: a request that must be reconstructable and is not, with nothing
+         * in the pipeline looking wrong.
+         */
+        if (this.#policy.requireRecording && this.#record === undefined) {
+            throw new Error('the host policy requires recording (HLM-09) but no journal sink was provided. Refusing to construct a broker '
+                + 'that would report recorded requests it never recorded; pass a sink or set requireRecording to false');
+        }
+    }
+    /** The host policy in force. */
+    get policy() {
+        return this.#policy;
+    }
+    /**
+     * Authorize a provider generation for one tool (HLM-02).
+     *
+     * The generation is CAPTURED here rather than read at dispatch time, so a provider that
+     * reloads between authorization and dispatch stops being authorized instead of being
+     * silently used under the old decision.
+     * @param toolName - the tool this authorization covers.
+     * @param provider - the provider.
+     */
+    authorize(toolName, provider) {
+        const grant = { toolName, provider, generation: provider.generation };
+        this.#grants.set(toolName, grant);
+        return grant;
+    }
+    /**
+     * Revoke a tool's authorization.
+     * @param toolName - the tool to revoke.
+     * @returns whether an authorization existed.
+     */
+    revoke(toolName) {
+        return this.#grants.delete(toolName);
+    }
+    /**
+     * The live authorization for a tool, or `undefined`.
+     *
+     * `undefined` covers both "never authorized" and "authorized for a generation this
+     * provider no longer is", because from a caller's point of view both mean the same
+     * thing: this invocation has no authorized executor. {@link resolveGrant} keeps the
+     * two apart for the error message.
+     * @param toolName - the tool to look up.
+     * @returns the grant, when it is still valid.
+     */
+    grantFor(toolName) {
+        const resolved = this.#resolveGrant(toolName);
+        return resolved.kind === 'ok' ? this.#grants.get(toolName) : undefined;
+    }
+    /** Resolve, keeping "missing" and "stale" distinct for the refusal reason. */
+    #resolveGrant(toolName) {
+        const grant = this.#grants.get(toolName);
+        if (grant === undefined)
+            return { kind: 'missing' };
+        const current = grant.provider.generation;
+        if (current !== grant.generation) {
+            return { kind: 'stale', authorized: grant.generation, current };
+        }
+        return { kind: 'ok', provider: grant.provider, generation: grant.generation };
+    }
+    /**
+     * Run one recipe invocation.
+     *
+     * Cancellation, policy refusals and provider failures all come back as outcomes rather
+     * than exceptions, so a caller that must report a result cannot lose one to an
+     * unhandled rejection. Use {@link runOrThrow} where an exception is the right shape.
+     * @param recipe - the recipe to run.
+     * @param args - the caller's arguments, validated against the recipe's inputs.
+     * @param options - the cancellation channel and deadline.
+     * @returns the outcome: never a success that carries no text.
+     */
+    async run(recipe, args, options = {}) {
+        const controller = new AbortController();
+        let cancelReason = 'the caller aborted the invocation';
+        const caller = options.signal;
+        const onCallerAbort = () => {
+            cancelReason = 'the caller aborted the invocation';
+            controller.abort();
+        };
+        if (caller !== undefined) {
+            if (caller.aborted) {
+                cancelReason = 'the caller aborted the invocation before it started';
+                controller.abort();
+            }
+            else {
+                caller.addEventListener('abort', onCallerAbort, { once: true });
+            }
+        }
+        const deadlineMs = options.deadlineMs;
+        const startedAt = performance.now();
+        const timer = deadlineMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                cancelReason = `the invocation deadline of ${deadlineMs}ms expired`;
+                controller.abort();
+            }, deadlineMs);
+        try {
+            return await this.#invoke(recipe, args, controller.signal, () => cancelReason, startedAt, options.policy ?? this.#policy);
+        }
+        finally {
+            // Cleaning up here is not tidiness: a listener left on a long-lived signal is a
+            // leak per invocation, and a timer left running keeps the process alive.
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (caller !== undefined)
+                caller.removeEventListener('abort', onCallerAbort);
+        }
+    }
+    /**
+     * Run one recipe invocation, throwing on failure or cancellation.
+     * @param recipe - the recipe to run.
+     * @param args - the caller's arguments.
+     * @param options - the cancellation channel and deadline.
+     * @returns the completed outcome.
+     * @throws BrokerError on any failure, including cancellation.
+     */
+    async runOrThrow(recipe, args, options = {}) {
+        const outcome = await this.run(recipe, args, options);
+        if (outcome.kind === 'completed')
+            return outcome;
+        if (outcome.kind === 'cancelled')
+            throw new BrokerError('CANCELLED', outcome.reason);
+        throw new BrokerError(outcome.code, outcome.reason);
+    }
+    /** The invocation itself: checks in the order they must happen, then one dispatch. */
+    async #invoke(recipe, args, signal, reason, startedAt, policy) {
+        // Cancellation first: a cancelled call must not do any of the work below, and the
+        // provider must not be called at all.
+        if (signal.aborted)
+            return { kind: 'cancelled', reason: reason() };
+        const binding = validateRecipeInputs(recipe, args);
+        if (!binding.ok) {
+            return { kind: 'failed', code: bindingCode(binding.errors), reason: binding.errors.join('; ') };
+        }
+        const resolved = this.#resolveGrant(recipe.tool.name);
+        if (resolved.kind === 'missing') {
+            return {
+                kind: 'failed',
+                code: 'EXECUTOR_NOT_CONFIGURED',
+                reason: `no executor is authorized for ${recipe.tool.name}. A recipe is a request for a host-approved harness `
+                    + 'model, not an authorization to reach one (RCP-05)',
+            };
+        }
+        if (resolved.kind === 'stale') {
+            return {
+                kind: 'failed',
+                code: 'EXECUTOR_NOT_CONFIGURED',
+                reason: `the authorization for ${recipe.tool.name} covers provider generation ${resolved.authorized}, but the `
+                    + `provider now reports generation ${resolved.current}. An authorization is for a generation, not for a `
+                    + 'name: re-authorize it rather than running new endpoint code under the old decision (HLM-02)',
+            };
+        }
+        const provider = resolved.provider;
+        /**
+         * ONE capability snapshot per invocation.
+         *
+         * Reading capabilities again after the call, or per check, is how one model's facts
+         * end up combined with another endpoint's after a concurrent switch (HLM-02).
+         */
+        const capabilities = provider.capabilities();
+        if (capabilities.inputModalities !== undefined && !capabilities.inputModalities.includes('text')) {
+            return {
+                kind: 'failed',
+                code: 'UNSUPPORTED_MODALITY',
+                reason: `provider "${provider.id}" declares input modalities ${capabilities.inputModalities.join(', ')}, `
+                    + 'which do not include text; a recipe prompt cannot be sent as a modality the model does not accept',
+            };
+        }
+        if (capabilities.outputModalities !== undefined && !capabilities.outputModalities.includes('text')) {
+            return {
+                kind: 'failed',
+                code: 'UNSUPPORTED_MODALITY',
+                reason: `provider "${provider.id}" declares output modalities ${capabilities.outputModalities.join(', ')}, `
+                    + 'which do not include text; this recipe cannot consume its output',
+            };
+        }
+        const values = binding.values;
+        const images = imagesOf(recipe, values);
+        if (images.length > 0 && capabilities.inputModalities !== undefined
+            && !capabilities.inputModalities.includes('image')) {
+            return {
+                kind: 'failed',
+                code: 'IMAGE_INPUT_UNAVAILABLE',
+                reason: `provider "${provider.id}" declares input modalities ${capabilities.inputModalities.join(', ')}, `
+                    + 'which do not include image; the image capability flag is not allowed to override the declared modalities',
+            };
+        }
+        if (images.length > 0) {
+            const imagesCapability = imageCapability(capabilities.images);
+            if (imagesCapability === 'unsupported') {
+                return {
+                    kind: 'failed',
+                    code: 'IMAGE_INPUT_UNAVAILABLE',
+                    reason: `${recipe.tool.name} binds ${images.length} image input(s) but provider "${provider.id}" reports no `
+                        + 'image support. Refusing rather than sending the text alone: a model asked to describe an image it never '
+                        + 'received produces a fluent invention, and that is worse than an error (HLM-11)',
+                };
+            }
+            if (imagesCapability === 'unknown') {
+                return {
+                    kind: 'failed',
+                    code: 'EXECUTOR_CAPABILITY_UNKNOWN',
+                    reason: `provider "${provider.id}" has not reported whether it accepts images, and ${recipe.tool.name} binds `
+                        + 'an image input. An unevaluated capability is not a capability: refusing rather than assuming it '
+                        + '(MODEL-06)',
+                };
+            }
+        }
+        /**
+         * The image ceiling is the INTERSECTION of every limit (HLM-07, RES-10).
+         *
+         * A narrowed host policy must be able to refuse images a recipe permits, which is
+         * the only direction a limit may move.
+         */
+        const imageCeiling = Math.min(recipe.imageInputs.max, policy.imageInputs, INITIAL_MAX_IMAGE_INPUTS);
+        if (images.length > imageCeiling) {
+            return {
+                kind: 'failed',
+                code: 'MODEL_BUDGET_EXCEEDED',
+                reason: `${images.length} image input(s) supplied against an effective ceiling of ${imageCeiling} (recipe `
+                    + `${recipe.imageInputs.max}, host ${policy.imageInputs}, RES-10 ${INITIAL_MAX_IMAGE_INPUTS})`,
+            };
+        }
+        if (!permitsDestination(policy, provider.destination)) {
+            return {
+                kind: 'failed',
+                code: 'EXECUTOR_NOT_CONFIGURED',
+                reason: `provider "${provider.id}" is a ${provider.destination} destination and the policy in force permits `
+                    + 'local destinations only. A local-only profile prohibits remote destinations however the tool was built, '
+                    + 'so this is refused rather than routed (RES-10)',
+            };
+        }
+        const maxOutputTokens = Math.min(recipe.maxOutputTokens, policy.outputTokens, capabilities.maxOutputTokens);
+        if (!Number.isInteger(maxOutputTokens) || maxOutputTokens < 1) {
+            return {
+                kind: 'failed',
+                code: 'MODEL_BUDGET_EXCEEDED',
+                reason: `the effective output-token ceiling is ${maxOutputTokens} (recipe ${recipe.maxOutputTokens}, host `
+                    + `${policy.outputTokens}, provider ${capabilities.maxOutputTokens}). A call permitted to produce `
+                    + 'nothing cannot produce a result (RES-10)',
+            };
+        }
+        /**
+         * Recording is settled BEFORE dispatch.
+         *
+         * HLM-09: if mandatory recording conflicts with policy, refuse rather than silently
+         * drop it. Refusing here means no provider is called, so a refused invocation is not
+         * a billed one.
+         */
+        if (!recipe.policy.record && policy.requireRecording) {
+            return {
+                kind: 'failed',
+                code: 'CAPTURE_POLICY_CONFLICT',
+                reason: `${recipe.tool.name} declares record: false while the host requires the prepared request to be `
+                    + 'journaled. Refusing rather than running unrecorded: a request that must be reconstructable and is not is '
+                    + 'the failure HLM-09 names, and it leaves nothing in the pipeline looking wrong',
+            };
+        }
+        let recorded = false;
+        /**
+         * The request is built BEFORE the journal entry, and the entry quotes THAT request.
+         *
+         * HLM-09 asks the journal to record the exact prepared request. Rendering the prompt
+         * separately for the entry would make the record a second rendering that merely ought
+         * to agree with the one that was sent; quoting the request's own prompt makes the two
+         * the same string by construction.
+         */
+        const request = buildIsolatedRequest(recipe, values, maxOutputTokens, signal);
+        if (recipe.policy.record) {
+            const sink = this.#record;
+            if (sink === undefined) {
+                return {
+                    kind: 'failed',
+                    code: 'CAPTURE_POLICY_CONFLICT',
+                    reason: 'recording is required but no journal sink is configured, so the prepared request would be lost',
+                };
+            }
+            const entry = {
+                kind: 'harness-model-auxiliary-call',
+                toolName: recipe.tool.name,
+                contractId: recipe.tool.contractId,
+                recipeId: recipe.id,
+                recipeVersion: recipe.version,
+                providerId: provider.id,
+                providerGeneration: resolved.generation,
+                destination: provider.destination,
+                maxOutputTokens,
+                imageCount: images.length,
+                prompt: request.prompt,
+                context: 'recipe-only',
+            };
+            try {
+                await sink(entry);
+                recorded = true;
+            }
+            catch (error) {
+                return {
+                    kind: 'failed',
+                    code: 'RECORDING_FAILED',
+                    reason: `the auxiliary-call journal rejected the entry (${messageOf(error)}), so the call did not run. A call `
+                        + 'whose record cannot be written is not one this broker will make',
+                };
+            }
+        }
+        const dispatched = await dispatch(provider, request, signal, reason);
+        if (dispatched.kind === 'cancelled')
+            return { kind: 'cancelled', reason: dispatched.reason };
+        if (dispatched.kind === 'failed') {
+            return { kind: 'failed', code: 'PROVIDER_FAILED', reason: dispatched.reason };
+        }
+        /**
+         * A signal aborted while the provider was working is a cancellation, whatever came
+         * back.
+         *
+         * Checking after the await is the difference between "we stopped asking" and "we
+         * stopped caring": the caller cancelled, so a result that arrived afterwards is not
+         * one it asked for, and reporting it as a success would attach an answer to a
+         * cancelled invocation (HLM-10).
+         */
+        if (signal.aborted) {
+            return { kind: 'cancelled', reason: `${reason()}; the provider's result was discarded rather than reported` };
+        }
+        /**
+         * The generation is rechecked when the call returns, and a change makes the result
+         * UNATTRIBUTABLE.
+         *
+         * HLM-02 forbids combining one model's capability facts with another endpoint, and a
+         * provider that reloads while the call is in flight leaves the broker holding a result
+         * it cannot honestly attribute to either generation. Reporting it under the resolved
+         * generation would be a receipt claiming provenance the broker does not have.
+         */
+        if (provider.generation !== resolved.generation) {
+            return {
+                kind: 'failed',
+                code: 'PROVIDER_FAILED',
+                reason: `provider "${provider.id}" changed generation from ${resolved.generation} to ${provider.generation} `
+                    + 'while the call was in flight, so the result cannot be attributed to the endpoint this invocation '
+                    + 'resolved. Refusing rather than reporting it under either generation (HLM-02)',
+            };
+        }
+        const completion = dispatched.completion;
+        const identity = {
+            provider: { id: provider.id, generation: resolved.generation, destination: provider.destination },
+            recipe: {
+                id: recipe.id,
+                version: recipe.version,
+                toolName: recipe.tool.name,
+                contractId: recipe.tool.contractId,
+            },
+        };
+        switch (completion.kind) {
+            case 'refused':
+                return {
+                    kind: 'failed',
+                    code: 'MODEL_REFUSED',
+                    reason: `the model declined: ${completion.reason}. A refusal is an error and never an empty result, because a `
+                        + 'caller writing an empty result into a document sees a blank field rather than a failure',
+                };
+            case 'truncated':
+                return {
+                    kind: 'failed',
+                    code: 'MODEL_OUTPUT_TRUNCATED',
+                    reason: 'the generation was cut short, so no complete result was produced. Partial prose is not a successful '
+                        + 'result (HLM-07)',
+                };
+            case 'tool_call':
+                return {
+                    kind: 'failed',
+                    code: 'UNEXPECTED_MODEL_TOOL_CALL',
+                    reason: `the provider emitted a tool call for "${completion.toolName}". No tool catalog was supplied, so a `
+                        + 'tool call is not executed and no agent loop continues from it (HLM-06)',
+                };
+            case 'text': {
+                if (completion.text.trim().length === 0) {
+                    return {
+                        kind: 'failed',
+                        code: 'INVALID_MODEL_OUTPUT',
+                        reason: 'the provider returned empty text. An empty completion is not a result: reporting it as one '
+                            + 'produces an empty title, an empty description and no error anywhere',
+                    };
+                }
+                const usage = completion.usage ?? {
+                    known: false,
+                    reason: 'the provider reported no usage for this call',
+                };
+                return {
+                    kind: 'completed',
+                    text: completion.text,
+                    usage,
+                    aggregate: {
+                        attempts: 1,
+                        images: images.length,
+                        elapsedMs: Math.max(0, performance.now() - startedAt),
+                        usage,
+                    },
+                    recorded,
+                    ...identity,
+                };
+            }
+        }
+    }
+}
+/**
+ * Dispatch one call, honouring cancellation and turning a provider throw into a failure.
+ * @param provider - the provider.
+ * @param request - the isolated request.
+ * @param signal - the cancellation channel.
+ * @param reason - reads the current cancellation reason.
+ * @returns how the dispatch settled.
+ */
+async function dispatch(provider, request, signal, reason) {
+    if (signal.aborted)
+        return { kind: 'cancelled', reason: reason() };
+    let onAbort;
+    const cancelled = new Promise((resolve) => {
+        onAbort = () => resolve({ kind: 'cancelled', reason: reason() });
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([
+            provider.complete(request).then((completion) => ({ kind: 'completion', completion }), 
+            // The provider's own rejection is handled here rather than escaping as an
+            // unhandled rejection after a cancellation already won the race.
+            (error) => ({ kind: 'failed', reason: `provider "${provider.id}" failed: ${messageOf(error)}` })),
+            cancelled,
+        ]);
+    }
+    finally {
+        if (onAbort !== undefined)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
+//# sourceMappingURL=broker.js.map