/**
 * defineAgentRecipe — declare a named, versioned composition.
 *
 * Pattern: a validating factory that freezes. No class, no registry, no
 *          instance state — the "recipes over primitives" instruction taken
 *          literally.
 * Role:    recipes/ layer, pure. The validation it runs is the SAME function
 *          `AgentBuilder.recipe()` runs, so a hand-written literal cannot get
 *          past the checks the factory makes; the factory only moves the
 *          refusal to the declaration, which is where the fix is.
 * Emits:   N/A.
 *
 * ## Why it freezes
 *
 * A recipe is handed to `.recipe()` on one agent and, typically, to `.recipe()`
 * on several more. A mutable one is a shared object that a single consumer can
 * edit for everybody — and the edit would be invisible on the record, because
 * the manifest reports the id and the version, both of which would still say
 * what they always said. `Object.freeze` is shallow, which is exactly the
 * depth that matters here: the four fields are three strings and a function.
 */
import type { AgentRecipe } from './types.js';
/**
 * A recipe declaration that cannot be honoured. Thrown by
 * {@link defineAgentRecipe} and by `AgentBuilder.recipe()` — the same class
 * from both doors, because it is the same mistake wherever it is caught.
 */
export declare class InvalidAgentRecipeError extends Error {
    readonly code: "ERR_INVALID_AGENT_RECIPE";
    /** Which field was refused (`'id'`, `'version'`, `'configure'`, `'shape'`). */
    readonly field: string;
    constructor(field: string, message: string);
}
/**
 * Validate a recipe declaration, or refuse it by name.
 *
 * Total over `unknown`: this is the one gate, and it is called from the
 * factory AND from `.recipe()`, so no recipe reaches an agent unvalidated.
 *
 * @param value    - the candidate declaration.
 * @param callSite - the API the author called, named in every refusal.
 */
export declare function assertAgentRecipe(value: unknown, callSite: string): asserts value is AgentRecipe;
/**
 * Declare a recipe: a name, a version, and the builder calls it stands for.
 *
 * Validates every field and returns a frozen object. Refusals name the field
 * and the fix — `defineAgentRecipe` is where a bad id or version costs one
 * line, and `.recipe()` is where the same mistake costs a stack trace through
 * somebody else's app.
 *
 * @example  the composition an app imports and applies
 * ```ts
 * import { defineAgentRecipe } from 'agentfootprint/recipes';
 *
 * export const supportDesk = defineAgentRecipe({
 *   id: 'support-desk',
 *   version: '1.2.0',
 *   description: 'Order lookup + refund policy, the way support runs it.',
 *   configure: (agent) => {
 *     agent.system('You answer support questions.').tool(lookupOrder);
 *   },
 * });
 *
 * const agent = Agent.create({ provider, model }).recipe(supportDesk).build();
 * ```
 */
export declare function defineAgentRecipe(recipe: AgentRecipe): AgentRecipe;