agentfootprint 9.47.0 → 9.48.0

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;

package/dist/esm/recipes/provenance.js

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+/** The one `local` value. A frozen singleton — it carries no data. */
+export const LOCAL_SOURCE = Object.freeze({ kind: 'local' });
+/**
+ * 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 function describeRecipeSource(source) {
+    if (source === undefined) {
+        return ('an earlier registration with no recorded source (a builder method mounted it; ' +
+            'this builder did not attribute it)');
+    }
+    if (source.kind === 'local')
+        return 'this agent, directly';
+    const chain = [...source.stack].reverse().map((r) => `recipe '${r.id}' ${r.version}`);
+    return chain.join(' ← applied by ');
+}
+//# sourceMappingURL=provenance.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../../../src/recipes/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAeH,sEAAsE;AACtE,MAAM,CAAC,MAAM,YAAY,GAAiB,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAgB,EAAE,CAAC,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAgC;IACnE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,CACL,gFAAgF;YAChF,oCAAoC,CACrC,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,sBAAsB,CAAC;IAC3D,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;AACtC,CAAC"}

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

@@ -0,0 +1,134 @@
+/**
+ * recipes/types — the declared unit of agent configuration.
+ *
+ * Pattern: a data DECLARATION over an existing fluent builder. No class, no
+ *          registry, no lifecycle. The repo's own instruction is that named
+ *          patterns are recipes over primitives rather than new machinery, and
+ *          this file is that instruction taken literally.
+ * Role:    recipes/ layer, pure. Nothing here imports the engine, a provider,
+ *          or a store — the only agentfootprint type it names is
+ *          {@link AgentBuilder}, and it names it as a TYPE.
+ * Emits:   N/A. `AgentBuilder.recipe()` records the row; `runManifest` reports
+ *          it.
+ *
+ * ## The gap this closes
+ *
+ * Every capability an agent needs already ships. What did not ship was a
+ * declared, versioned, inspectable unit of CONFIGURATION. So an agent's setup
+ * lived as prose in an example, was copy-pasted into an app, drifted there, and
+ * afterwards nothing on the run could say which composition produced the agent
+ * that answered. Two runs of "the support agent" could differ in every tool and
+ * every instruction and be indistinguishable on the record.
+ *
+ * A recipe is the missing noun: a name, a version, and a function that calls
+ * the builder methods that already exist.
+ *
+ * ```ts
+ * 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();
+ * ```
+ *
+ * ## No lifecycle magic — stated here because it is the load-bearing limit
+ *
+ * A recipe composes CONFIGURATION and nothing else:
+ *
+ *   • nothing is registered anywhere — a recipe is not discovered, not looked
+ *     up by name, and not resolved from a registry. You import the object and
+ *     hand it to `.recipe()`. There is no global map to go stale, and no
+ *     "which version of `support-desk` is installed" question;
+ *   • nothing is closable — a recipe holds no connection, no handle and no
+ *     process. It never gets a `close()`, a `dispose()` or a teardown hook,
+ *     and it is never awaited: `configure` is synchronous because `build()`
+ *     is (an `async configure` is refused by name rather than silently not
+ *     awaited);
+ *   • nothing is deferred — every call `configure` makes happens during
+ *     `.recipe()`, at the position in the chain where you wrote it. There is
+ *     no later phase in which a recipe acts, so a run's behaviour is decided
+ *     entirely by the builder calls you can read.
+ *
+ * That is deliberately thin. The thing being named is a COMPOSITION, and a
+ * composition that also owned a resource would be a component wearing a
+ * composition's name — the shape that makes "who closed the pool?" unanswerable
+ * two releases later.
+ */
+import type { AgentBuilder } from '../core/agent/AgentBuilder.js';
+/**
+ * A named, versioned composition over the agent builder.
+ *
+ * Build one with {@link defineAgentRecipe}, which validates every field and
+ * freezes the result. A hand-written object literal is accepted by
+ * `.recipe()` too — it runs the SAME validation — so a recipe cannot reach an
+ * agent without passing the checks; the factory only moves the refusal to the
+ * declaration, where the fix is.
+ */
+export interface AgentRecipe {
+    /**
+     * The composition's plain name — lower-case words joined by single hyphens
+     * (`support-desk`, `triage`, `refund-policy`).
+     *
+     * It carries NO version: `support-desk-2` is refused, because the version
+     * axis already exists as its own field and an id that encodes one produces
+     * two names for one composition, neither of which can be grouped on.
+     */
+    readonly id: string;
+    /**
+     * The composition's version, as SemVer 2.0.0 (`'1.2.0'`, `'2.0.0-rc.1'`).
+     *
+     * A version is what makes a recipe row on a run manifest worth reading: two
+     * runs of `support-desk` that answered differently are a mystery until the
+     * record says one was `1.2.0` and the other `1.3.0`.
+     */
+    readonly version: string;
+    /** What this composition is for, in one sentence. Optional, and never
+     *  reported on the wire — the manifest carries the id and the version only. */
+    readonly description?: string;
+    /**
+     * Apply the composition: call the builder methods this recipe stands for.
+     *
+     * Runs SYNCHRONOUSLY, exactly once, at the `.recipe()` call site. The return
+     * value is ignored — `AgentBuilder` is mutated in place and every method
+     * returns the same object — so `(agent) => agent.system('…').tool(t)` and a
+     * statement body are the same program.
+     */
+    configure(builder: AgentBuilder): void;
+}
+/**
+ * One applied recipe, as the run manifest reports it: the id and the version,
+ * never the description and never the function.
+ *
+ * The two stay SEPARATE FIELDS on purpose. A composed key (`'support-desk@1.2.0'`)
+ * would be one string that two different pairs could produce as soon as either
+ * half is allowed to contain the separator — the collision class this repo has
+ * fixed seven times. Nothing here ever joins them.
+ */
+export interface AppliedRecipe {
+    readonly id: string;
+    readonly version: string;
+}
+/**
+ * What happens when a recipe introduces a tool name or an injection id that is
+ * already taken.
+ *
+ * `'error'` is the only policy that exists, and it is the default. The
+ * alternatives a reader will reach for — skip the recipe's version, let it
+ * replace what is there, rename one automatically — are real designs, and none
+ * of them is implemented: each has to answer where the drop is RECORDED, and a
+ * conflict resolved silently is exactly the "accepted and quietly wrong" shape
+ * this library refuses. So an unimplemented policy is refused by name (see
+ * {@link resolveRecipeConflictPolicy}) rather than approximated by the one that
+ * ships.
+ */
+export type RecipeConflictPolicy = 'error';
+/** Options for `AgentBuilder.recipe(recipe, options)`. */
+export interface RecipeOptions {
+    /** See {@link RecipeConflictPolicy}. Default `'error'`. */
+    readonly conflict?: RecipeConflictPolicy;
+}