agentfootprint 9.46.3 → 9.48.0

package/dist/esm/observe.js.map

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

package/dist/esm/recipes/apply.d.ts

@@ -0,0 +1,67 @@
+/**
+ * apply — the pure half of applying a recipe.
+ *
+ * Pattern: policy resolution + the sentences the applier raises. Pure, so
+ *          every refusal can be read and tested without building an agent.
+ * Role:    recipes/ layer. `AgentBuilder.recipe()` is the only caller; it owns
+ *          the mutation, this file owns the words.
+ * Emits:   N/A.
+ */
+import { type RecipeSource } from './provenance.js';
+import type { AppliedRecipe, RecipeConflictPolicy } from './types.js';
+/**
+ * Resolve the conflict policy, or refuse the requested one BY NAME.
+ *
+ * The three a reader reaches for are named in the refusal because each is a
+ * real design and none is implemented: every one of them has to answer where
+ * the dropped registration is RECORDED, and until it does, running it as
+ * `'error'`'s quiet cousin would be the accepted-and-silently-wrong shape this
+ * library refuses. So the unimplemented policy is refused rather than
+ * approximated by the one that ships.
+ */
+export declare function resolveRecipeConflictPolicy(value: unknown, callSite: string): RecipeConflictPolicy;
+/**
+ * The refusal for a name two sources both registered.
+ *
+ * Raised only when at least one side came from a recipe. A collision between
+ * two direct builder calls keeps the sentence it has always had — the message
+ * an app already reads in its tests should not change because a feature it does
+ * not use shipped.
+ *
+ * `what` is the word the reader uses (`'tool name'` / `'injection id'`);
+ * `existing` is who registered it first and `incoming` who is registering it
+ * now, either of which may be `undefined` for the unattributed case;
+ * `callSite` is the API being called, e.g. `Agent.tool()`.
+ */
+export declare function duplicateRegistrationRefusal(params: {
+    readonly what: 'tool name' | 'injection id';
+    readonly name: string;
+    readonly existing: RecipeSource | undefined;
+    readonly incoming: RecipeSource | undefined;
+    readonly callSite: string;
+}): string;
+/** The refusal for one composition applied twice to one agent. */
+export declare function duplicateRecipeRefusal(params: {
+    readonly existing: AppliedRecipe;
+    readonly incoming: AppliedRecipe;
+    readonly callSite: string;
+}): string;
+/**
+ * The refusal for a recipe that applies ITSELF, directly or through another.
+ *
+ * A SEPARATE sentence from {@link duplicateRecipeRefusal}, because these are two
+ * different facts and the fix is different for each: "already applied" means the
+ * chain names one composition twice, and "currently applying" means the
+ * composition is its own ancestor and would never terminate. Telling the author
+ * their recursion is a duplicate would send them to look at the wrong line.
+ *
+ * `stack` is the application chain, outermost first, so the message can show the
+ * cycle rather than assert one.
+ */
+export declare function recursiveRecipeRefusal(params: {
+    readonly stack: readonly AppliedRecipe[];
+    readonly incoming: AppliedRecipe;
+    readonly callSite: string;
+}): string;
+/** The refusal for `configure` returning a promise. */
+export declare function asyncConfigureRefusal(recipe: AppliedRecipe, callSite: string): string;

package/dist/esm/recipes/apply.js

@@ -0,0 +1,117 @@
+/**
+ * apply — the pure half of applying a recipe.
+ *
+ * Pattern: policy resolution + the sentences the applier raises. Pure, so
+ *          every refusal can be read and tested without building an agent.
+ * Role:    recipes/ layer. `AgentBuilder.recipe()` is the only caller; it owns
+ *          the mutation, this file owns the words.
+ * Emits:   N/A.
+ */
+import { describeRecipeSource } from './provenance.js';
+/** The policies that exist. One, today — see {@link RecipeConflictPolicy}. */
+const CONFLICT_POLICIES = ['error'];
+/**
+ * Resolve the conflict policy, or refuse the requested one BY NAME.
+ *
+ * The three a reader reaches for are named in the refusal because each is a
+ * real design and none is implemented: every one of them has to answer where
+ * the dropped registration is RECORDED, and until it does, running it as
+ * `'error'`'s quiet cousin would be the accepted-and-silently-wrong shape this
+ * library refuses. So the unimplemented policy is refused rather than
+ * approximated by the one that ships.
+ */
+export function resolveRecipeConflictPolicy(value, callSite) {
+    if (value === undefined)
+        return 'error';
+    if (CONFLICT_POLICIES.includes(value)) {
+        return value;
+    }
+    throw new Error(`${callSite}: conflict policy ${typeof value === 'string' ? `'${value}'` : String(value)} is not implemented. The only policy this library has is 'error' (the default): a tool ` +
+        `name or injection id a recipe introduces that is already taken refuses at build, naming ` +
+        `both sources.\n\n` +
+        `'skip', 'replace' and automatic renaming are each a real design, and each one has to ` +
+        `answer the same question first — where the dropped or overridden registration is ` +
+        `RECORDED. A composition that silently loses a tool answers a turn without it and says ` +
+        `nothing, which is the failure this option exists to prevent, so an unimplemented policy ` +
+        `is refused here rather than quietly run as 'error'.\n\n` +
+        `To compose recipes that overlap today: rename one of the colliding registrations, or ` +
+        `have the recipe export the piece so the app registers it once itself.`);
+}
+/**
+ * The refusal for a name two sources both registered.
+ *
+ * Raised only when at least one side came from a recipe. A collision between
+ * two direct builder calls keeps the sentence it has always had — the message
+ * an app already reads in its tests should not change because a feature it does
+ * not use shipped.
+ *
+ * `what` is the word the reader uses (`'tool name'` / `'injection id'`);
+ * `existing` is who registered it first and `incoming` who is registering it
+ * now, either of which may be `undefined` for the unattributed case;
+ * `callSite` is the API being called, e.g. `Agent.tool()`.
+ */
+export function duplicateRegistrationRefusal(params) {
+    const { what, name, existing, incoming, callSite } = params;
+    const consequence = what === 'tool name'
+        ? `The model dispatches tools BY NAME, so two tools under one name is a coin flip whose ` +
+            `loser is never called and never mentioned.`
+        : `An injection id is how the engine addresses one piece of context — activation, ` +
+            `caching, the trace and every recorder key on it — so two under one name is one of ` +
+            `them silently never reaching the model.`;
+    return (`${callSite}: duplicate ${what} '${name}' — already registered by ` +
+        `${describeRecipeSource(existing)}, and now by ${describeRecipeSource(incoming)}.\n\n` +
+        `${consequence}\n\n` +
+        `Pick one: rename one of them, or have the recipe export the piece so the app registers it ` +
+        `once itself. There is no conflict policy that picks a winner for you — see ` +
+        `.recipe(recipe, { conflict }).`);
+}
+/** The refusal for one composition applied twice to one agent. */
+export function duplicateRecipeRefusal(params) {
+    const { existing, incoming, callSite } = params;
+    const sameVersion = existing.version === incoming.version;
+    return (`${callSite}: recipe '${incoming.id}' is already applied to this agent ` +
+        `${sameVersion
+            ? `(both at ${existing.version})`
+            : `at ${existing.version}, and this one is ${incoming.version}`}.\n\n` +
+        `${sameVersion
+            ? `Applying it twice would run its builder calls twice — which for anything that ` +
+                `refuses a duplicate (a tool, an injection) fails on the second pass, and for ` +
+                `anything that does not would silently double it.`
+            : `One agent runs ONE version of a composition. Two would each apply their builder ` +
+                `calls over the other, and the manifest would carry two rows for a composition that ` +
+                `cannot be two things at once — nothing downstream could say which one shaped the ` +
+                `answer.`}\n\n` +
+        `Apply it once${sameVersion ? '' : `, at the version you mean`}.`);
+}
+/**
+ * The refusal for a recipe that applies ITSELF, directly or through another.
+ *
+ * A SEPARATE sentence from {@link duplicateRecipeRefusal}, because these are two
+ * different facts and the fix is different for each: "already applied" means the
+ * chain names one composition twice, and "currently applying" means the
+ * composition is its own ancestor and would never terminate. Telling the author
+ * their recursion is a duplicate would send them to look at the wrong line.
+ *
+ * `stack` is the application chain, outermost first, so the message can show the
+ * cycle rather than assert one.
+ */
+export function recursiveRecipeRefusal(params) {
+    const { stack, incoming, callSite } = params;
+    const cycle = [...stack, incoming].map((r) => `'${r.id}' ${r.version}`).join(' → ');
+    return (`${callSite}: recipe '${incoming.id}' ${incoming.version} is applying itself — ${cycle}.\n\n` +
+        `\`configure\` runs immediately, so this would recurse until the stack ran out rather than ` +
+        `converge on a configured agent.\n\n` +
+        `Pull the shared part into a THIRD recipe and have both apply that one, or drop the ` +
+        `self-application.`);
+}
+/** The refusal for `configure` returning a promise. */
+export function asyncConfigureRefusal(recipe, callSite) {
+    return (`${callSite}: recipe '${recipe.id}' ${recipe.version} returned a promise from \`configure\`. ` +
+        `A recipe composes CONFIGURATION only, and \`build()\` is synchronous — there is no phase ` +
+        `in which this library would await it, so the work would run after the agent was already ` +
+        `built and land on nothing.\n\n` +
+        `Do the async part before you build (\`const tools = await mcpClient(…).tools()\`), and ` +
+        `have the recipe take what it needs: a recipe can be a plain function of its inputs that ` +
+        `RETURNS a recipe (\`export const crm = (tools) => defineAgentRecipe({ … }))\`.`);
+}
+//# sourceMappingURL=apply.js.map

package/dist/esm/recipes/apply.js.map

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

package/dist/esm/recipes/defineAgentRecipe.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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;

package/dist/esm/recipes/defineAgentRecipe.js

@@ -0,0 +1,112 @@
+/**
+ * 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 { isPlainRecipeId, recipeIdRefusal } from './identifier.js';
+import { isSemverVersion, versionRefusal } from './version.js';
+/** The fields a recipe declares. Anything else is a typo — see the refusal. */
+const RECIPE_KEYS = ['id', 'version', 'description', 'configure'];
+/**
+ * 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 class InvalidAgentRecipeError extends Error {
+    code = 'ERR_INVALID_AGENT_RECIPE';
+    /** Which field was refused (`'id'`, `'version'`, `'configure'`, `'shape'`). */
+    field;
+    constructor(field, message) {
+        super(message);
+        this.name = 'InvalidAgentRecipeError';
+        this.field = field;
+    }
+}
+/**
+ * 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 function assertAgentRecipe(value, callSite) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new InvalidAgentRecipeError('shape', `${callSite}: a recipe is an object { id, version, description?, configure }, not ` +
+            `${value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value}.`);
+    }
+    const record = value;
+    // Unknown keys first: `name:` instead of `id:` fails every later check with a
+    // message about the field that is MISSING, which sends the reader looking for
+    // a field they can plainly see they wrote.
+    const unknown = Object.keys(record).filter((key) => !RECIPE_KEYS.includes(key));
+    if (unknown.length > 0) {
+        throw new InvalidAgentRecipeError('shape', `${callSite}: unknown field${unknown.length > 1 ? 's' : ''} ${unknown
+            .map((k) => `'${k}'`)
+            .join(', ')}. A recipe declares exactly ${RECIPE_KEYS.map((k) => `\`${k}\``).join(', ')} ` +
+            `— everything else about the agent is expressed by the builder calls \`configure\` ` +
+            `makes, which is the whole point of composing over the builder instead of inventing a ` +
+            `second configuration format.`);
+    }
+    if (!isPlainRecipeId(record.id)) {
+        throw new InvalidAgentRecipeError('id', recipeIdRefusal(callSite, record.id));
+    }
+    if (!isSemverVersion(record.version)) {
+        throw new InvalidAgentRecipeError('version', versionRefusal(callSite, record.version));
+    }
+    if (record.description !== undefined && typeof record.description !== 'string') {
+        throw new InvalidAgentRecipeError('description', `${callSite}: description must be a string (one sentence saying what this composition is ` +
+            `for), or omitted. Got ${typeof record.description}.`);
+    }
+    if (typeof record.configure !== 'function') {
+        throw new InvalidAgentRecipeError('configure', `${callSite}: configure must be a function (builder) => void — the builder calls this ` +
+            `composition stands for. Got ${record.configure === undefined ? 'nothing' : typeof record.configure}. A recipe with no \`configure\` configures nothing: it would apply cleanly, change ` +
+            `no behaviour, and still put a row on the run manifest claiming it shaped the agent.`);
+    }
+}
+/**
+ * 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 function defineAgentRecipe(recipe) {
+    assertAgentRecipe(recipe, 'defineAgentRecipe');
+    return Object.freeze({ ...recipe });
+}
+//# sourceMappingURL=defineAgentRecipe.js.map

package/dist/esm/recipes/defineAgentRecipe.js.map

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

package/dist/esm/recipes/identifier.d.ts

@@ -0,0 +1,40 @@
+/**
+ * identifier — the plain-name rule for a recipe id.
+ *
+ * Pattern: a total predicate + a refusal sentence. Pure, no dependencies.
+ * Role:    recipes/ layer. Used by `defineAgentRecipe` and by the same
+ *          validation `AgentBuilder.recipe()` runs on a hand-written literal.
+ * Emits:   N/A.
+ *
+ * ## Two rules, and the second one is the interesting one
+ *
+ * 1. **A plain name.** Lower-case words joined by single hyphens:
+ *    `support-desk`, `triage`, `refund-policy`. The id is what a person reads
+ *    on a run manifest, in a conflict refusal and in a bug report, so it is
+ *    spelled the way the rest of this library's public names are — for the
+ *    common reader, not for the implementation.
+ *
+ * 2. **No version suffix.** `support-desk-2` and `support-desk-v2` are refused.
+ *    A recipe already HAS a version field; an id that also encodes one produces
+ *    two names for one composition, and then nothing groups: runs of `-2` and
+ *    runs of the original look like two unrelated agents on the record, while
+ *    the field that exists to tell them apart says `1.0.0` on both.
+ *
+ * ## The honest limit of rule 2
+ *
+ * It matches the version-suffix SHAPES — a final hyphen-separated segment that
+ * is nothing but digits, optionally preceded by `v`. It does NOT catch an id
+ * that merely ends in a digit, because `oauth2`, `s3-archive` and `sha256` are
+ * real words and refusing them would be worse than missing `triage2`. Stated
+ * rather than implied: this check narrows a mistake, it does not eliminate it.
+ */
+/** Whether `value` is a plain recipe id. Total: any input, no throw. */
+export declare function isPlainRecipeId(value: unknown): value is string;
+/**
+ * The sentence a bad id gets. Names the value and the specific rule it broke —
+ * the version-suffix case in particular, because the fix there is not
+ * "spell it differently" but "use the field that already exists".
+ *
+ * @param callSite - the API the author called, e.g. `defineAgentRecipe`.
+ */
+export declare function recipeIdRefusal(callSite: string, value: unknown): string;

package/dist/esm/recipes/identifier.js

@@ -0,0 +1,95 @@
+/**
+ * identifier — the plain-name rule for a recipe id.
+ *
+ * Pattern: a total predicate + a refusal sentence. Pure, no dependencies.
+ * Role:    recipes/ layer. Used by `defineAgentRecipe` and by the same
+ *          validation `AgentBuilder.recipe()` runs on a hand-written literal.
+ * Emits:   N/A.
+ *
+ * ## Two rules, and the second one is the interesting one
+ *
+ * 1. **A plain name.** Lower-case words joined by single hyphens:
+ *    `support-desk`, `triage`, `refund-policy`. The id is what a person reads
+ *    on a run manifest, in a conflict refusal and in a bug report, so it is
+ *    spelled the way the rest of this library's public names are — for the
+ *    common reader, not for the implementation.
+ *
+ * 2. **No version suffix.** `support-desk-2` and `support-desk-v2` are refused.
+ *    A recipe already HAS a version field; an id that also encodes one produces
+ *    two names for one composition, and then nothing groups: runs of `-2` and
+ *    runs of the original look like two unrelated agents on the record, while
+ *    the field that exists to tell them apart says `1.0.0` on both.
+ *
+ * ## The honest limit of rule 2
+ *
+ * It matches the version-suffix SHAPES — a final hyphen-separated segment that
+ * is nothing but digits, optionally preceded by `v`. It does NOT catch an id
+ * that merely ends in a digit, because `oauth2`, `s3-archive` and `sha256` are
+ * real words and refusing them would be worse than missing `triage2`. Stated
+ * rather than implied: this check narrows a mistake, it does not eliminate it.
+ */
+/** Lower-kebab: starts with a letter, single hyphens, no trailing hyphen. */
+const PLAIN_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** A final segment that is a version: `2`, `07`, `v2`. */
+const VERSION_SUFFIX = /(?:^|-)v?\d+$/;
+/** Long enough for a sentence-like name, short enough to read in a refusal. */
+const MAX_LENGTH = 64;
+/** Whether `value` is a plain recipe id. Total: any input, no throw. */
+export function isPlainRecipeId(value) {
+    return (typeof value === 'string' &&
+        value.length <= MAX_LENGTH &&
+        PLAIN_NAME.test(value) &&
+        !VERSION_SUFFIX.test(value));
+}
+/**
+ * The sentence a bad id gets. Names the value and the specific rule it broke —
+ * the version-suffix case in particular, because the fix there is not
+ * "spell it differently" but "use the field that already exists".
+ *
+ * @param callSite - the API the author called, e.g. `defineAgentRecipe`.
+ */
+export function recipeIdRefusal(callSite, value) {
+    const shown = typeof value === 'string' ? `'${value}'` : `${typeof value}`;
+    if (typeof value === 'string' && PLAIN_NAME.test(value) && VERSION_SUFFIX.test(value)) {
+        const base = value.replace(VERSION_SUFFIX, '');
+        return (`${callSite}: id ${shown} ends in a version suffix. A recipe carries its version in the ` +
+            `\`version\` field, so an id that encodes one too gives a single composition two names — ` +
+            `and then nothing groups: runs of ${shown} and runs of '${base}' read as two unrelated ` +
+            `agents on the manifest, while the field that exists to tell them apart says the same ` +
+            `thing on both.\n\n` +
+            `Use id: '${base || 'a-plain-name'}' and bump \`version\` instead.`);
+    }
+    return (`${callSite}: id ${shown} is not a plain name. A recipe id is lower-case words joined by ` +
+        `single hyphens, starting with a letter, at most ${MAX_LENGTH} characters — ` +
+        `'support-desk', 'triage', 'refund-policy'.\n\n` +
+        `${diagnose(value)}\n\n` +
+        `It is spelled for the person who reads it on a run manifest, in a conflict refusal and in ` +
+        `a bug report — not for the code.`);
+}
+/** The specific rule broken, when the shape names one. */
+function diagnose(value) {
+    if (typeof value !== 'string') {
+        return `An id is a string; this was ${value === null ? 'null' : typeof value}.`;
+    }
+    if (value === '')
+        return 'This one is empty.';
+    if (value.length > MAX_LENGTH)
+        return `This one is ${value.length} characters.`;
+    if (value !== value.trim())
+        return 'This one has leading or trailing whitespace.';
+    if (/[A-Z]/.test(value)) {
+        return `Lower-case only — write '${value
+            .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+            .toLowerCase()}'.`;
+    }
+    if (/\s/.test(value))
+        return `Join the words with hyphens — '${value.trim().replace(/\s+/g, '-')}'.`;
+    if (/^[^a-z]/.test(value))
+        return 'It has to start with a letter.';
+    if (/-$/.test(value))
+        return 'It cannot end with a hyphen.';
+    if (/--/.test(value))
+        return 'Single hyphens only.';
+    return 'Allowed characters are a–z, 0–9 and single hyphens between them.';
+}
+//# sourceMappingURL=identifier.js.map

package/dist/esm/recipes/identifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier.js","sourceRoot":"","sources":["../../../src/recipes/identifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,6EAA6E;AAC7E,MAAM,UAAU,GAAG,iCAAiC,CAAC;AAErD,0DAA0D;AAC1D,MAAM,cAAc,GAAG,eAAe,CAAC;AAEvC,+EAA+E;AAC/E,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,MAAM,IAAI,UAAU;QAC1B,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;QACtB,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAC5B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,KAAc;IAC9D,MAAM,KAAK,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,EAAE,CAAC;IAC3E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtF,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;QAC/C,OAAO,CACL,GAAG,QAAQ,QAAQ,KAAK,iEAAiE;YACzF,0FAA0F;YAC1F,oCAAoC,KAAK,iBAAiB,IAAI,0BAA0B;YACxF,uFAAuF;YACvF,oBAAoB;YACpB,YAAY,IAAI,IAAI,cAAc,iCAAiC,CACpE,CAAC;IACJ,CAAC;IACD,OAAO,CACL,GAAG,QAAQ,QAAQ,KAAK,kEAAkE;QAC1F,mDAAmD,UAAU,gBAAgB;QAC7E,gDAAgD;QAChD,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM;QACxB,4FAA4F;QAC5F,kCAAkC,CACnC,CAAC;AACJ,CAAC;AAED,0DAA0D;AAC1D,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,+BAA+B,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,GAAG,CAAC;IAClF,CAAC;IACD,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,oBAAoB,CAAC;IAC9C,IAAI,KAAK,CAAC,MAAM,GAAG,UAAU;QAAE,OAAO,eAAe,KAAK,CAAC,MAAM,cAAc,CAAC;IAChF,IAAI,KAAK,KAAK,KAAK,CAAC,IAAI,EAAE;QAAE,OAAO,8CAA8C,CAAC;IAClF,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,4BAA4B,KAAK;aACrC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;aACtC,WAAW,EAAE,IAAI,CAAC;IACvB,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QAClB,OAAO,kCAAkC,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC;IACjF,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,gCAAgC,CAAC;IACnE,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,8BAA8B,CAAC;IAC5D,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,sBAAsB,CAAC;IACpD,OAAO,kEAAkE,CAAC;AAC5E,CAAC"}

package/dist/esm/recipes/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * recipes — the declared unit of agent configuration.
+ *
+ * The door: what `agentfootprint/recipes` publishes. Read `types.ts` for the
+ * argument (including the no-lifecycle limit) and README.md for the worked
+ * example.
+ *
+ * ## What is NOT here, and why
+ *
+ * The validators (`isPlainRecipeId`, `isSemverVersion`), the provenance
+ * formatter and every refusal sentence are internal. `AgentBuilder` imports
+ * them by module path, and this door stays the AUTHORING vocabulary: declare a
+ * recipe, catch the refusal, name the types. Publishing the plumbing would be
+ * surface nobody imports and everybody has to keep documented — and a recipe's
+ * whole claim is that it is a composition over primitives, not a second
+ * framework with an API of its own.
+ */
+export { defineAgentRecipe, InvalidAgentRecipeError } from './defineAgentRecipe.js';
+export type { AgentRecipe, AppliedRecipe, RecipeConflictPolicy, RecipeOptions } from './types.js';

package/dist/esm/recipes/index.js

@@ -0,0 +1,19 @@
+/**
+ * recipes — the declared unit of agent configuration.
+ *
+ * The door: what `agentfootprint/recipes` publishes. Read `types.ts` for the
+ * argument (including the no-lifecycle limit) and README.md for the worked
+ * example.
+ *
+ * ## What is NOT here, and why
+ *
+ * The validators (`isPlainRecipeId`, `isSemverVersion`), the provenance
+ * formatter and every refusal sentence are internal. `AgentBuilder` imports
+ * them by module path, and this door stays the AUTHORING vocabulary: declare a
+ * recipe, catch the refusal, name the types. Publishing the plumbing would be
+ * surface nobody imports and everybody has to keep documented — and a recipe's
+ * whole claim is that it is a composition over primitives, not a second
+ * framework with an API of its own.
+ */
+export { defineAgentRecipe, InvalidAgentRecipeError } from './defineAgentRecipe.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/recipes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/recipes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/esm/recipes/provenance.d.ts

@@ -0,0 +1,57 @@
+/**
+ * provenance — who registered this name.
+ *
+ * Pattern: a small value type + one formatter. Pure, no dependencies beyond
+ *          the recipe types.
+ * Role:    recipes/ layer. `AgentBuilder` records a {@link RecipeSource} beside
+ *          every tool name and injection id it takes, and reads it back when
+ *          two registrations collide.
+ * Emits:   N/A.
+ *
+ * ## Why provenance at all
+ *
+ * The builder has always refused a duplicate tool name — the model dispatches
+ * by name, so two tools called `search` is a coin flip. What it could not say
+ * was WHERE each one came from. With one recipe in the chain that answer stops
+ * being obvious ("I never registered a `search` tool") and with two it is
+ * unrecoverable without reading both recipes' source. A refusal that names both
+ * sides turns a hunt into a sentence.
+ *
+ * ## Three arms, because three things are true and one of them is "I do not know"
+ *
+ * `local` and `unattributed` are NOT the same fact, and collapsing them would
+ * make the refusal lie. `local` means: this builder watched you call
+ * `.tool()` / `.injection()` yourself. `unattributed` means: the name was
+ * already taken when the ledger was consulted and no source was recorded for
+ * it — the honest answer is that this builder does not know, and saying
+ * "you registered it" would send the reader to look in the one place it is not.
+ *
+ * The arm exists because there is more than one way into the injection list:
+ * `.injection()` is the funnel for the named flavors, and `.outputSchema()`
+ * mounts an instruction of its own. Both record a source today. A third site
+ * added later would not, and this arm is what keeps that omission honest
+ * instead of blaming the caller.
+ */
+import type { AppliedRecipe } from './types.js';
+/**
+ * Where a registered tool name or injection id came from.
+ *
+ * `stack` is the recipe application chain, OUTERMOST first: a recipe may apply
+ * another recipe, and the innermost one is the code that literally called the
+ * builder method.
+ */
+export type RecipeSource = {
+    readonly kind: 'local';
+} | {
+    readonly kind: 'recipe';
+    readonly stack: readonly AppliedRecipe[];
+};
+/** The one `local` value. A frozen singleton — it carries no data. */
+export declare const LOCAL_SOURCE: RecipeSource;
+/**
+ * Describe a source in a sentence fragment that reads inside a refusal.
+ *
+ * `undefined` is the unattributed case — see the header. It is a separate
+ * answer, never folded into `local`.
+ */
+export declare function describeRecipeSource(source: RecipeSource | undefined): string;