agentfootprint 9.47.0 → 9.49.0

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;
+}

package/dist/esm/recipes/types.js

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/recipes/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG"}

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

@@ -0,0 +1,38 @@
+/**
+ * version — is this string a version, or something that looks like one?
+ *
+ * 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.
+ *
+ * ## Why strict SemVer, and why a near-miss is refused rather than repaired
+ *
+ * The version is the half of a recipe row that makes the other half worth
+ * reading: two runs of `support-desk` that behaved differently are a mystery
+ * until the record says `1.2.0` and `1.3.0`. That only works if every producer
+ * spells versions the same way, so the ones that would quietly break grouping
+ * are refused at the declaration:
+ *
+ *   `'1.2'`      two runs, `'1.2'` and `'1.2.0'`, that are the same version and
+ *                do not group together.
+ *   `'v1.2.3'`   the same, with a decoration that sorts differently.
+ *   `'1.02.3'`   leading zeros: `'1.02.3'` and `'1.2.3'` again split one arm.
+ *   `'latest'`   a RANGE, not a version — it names whatever was installed, so
+ *   `'^1.2.3'`   the row would describe a different composition each week and
+ *   `'1.x'`      say nothing about the run it is stamped on.
+ *
+ * None is repaired. Padding `'1.2'` to `'1.2.0'` would put a version on the
+ * record that the author never wrote, which is the one thing a manifest field
+ * may not do.
+ */
+/** Whether `value` is a SemVer 2.0.0 version string. Total: any input, no throw. */
+export declare function isSemverVersion(value: unknown): value is string;
+/**
+ * The sentence a bad version gets. Names the value, the grammar, and the
+ * specific mistake when the shape identifies one — a refusal that only says
+ * "invalid" makes the author guess which half was wrong.
+ *
+ * @param callSite - the API the author called, e.g. `defineAgentRecipe`.
+ */
+export declare function versionRefusal(callSite: string, value: unknown): string;

package/dist/esm/recipes/version.js

@@ -0,0 +1,84 @@
+/**
+ * version — is this string a version, or something that looks like one?
+ *
+ * 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.
+ *
+ * ## Why strict SemVer, and why a near-miss is refused rather than repaired
+ *
+ * The version is the half of a recipe row that makes the other half worth
+ * reading: two runs of `support-desk` that behaved differently are a mystery
+ * until the record says `1.2.0` and `1.3.0`. That only works if every producer
+ * spells versions the same way, so the ones that would quietly break grouping
+ * are refused at the declaration:
+ *
+ *   `'1.2'`      two runs, `'1.2'` and `'1.2.0'`, that are the same version and
+ *                do not group together.
+ *   `'v1.2.3'`   the same, with a decoration that sorts differently.
+ *   `'1.02.3'`   leading zeros: `'1.02.3'` and `'1.2.3'` again split one arm.
+ *   `'latest'`   a RANGE, not a version — it names whatever was installed, so
+ *   `'^1.2.3'`   the row would describe a different composition each week and
+ *   `'1.x'`      say nothing about the run it is stamped on.
+ *
+ * None is repaired. Padding `'1.2'` to `'1.2.0'` would put a version on the
+ * record that the author never wrote, which is the one thing a manifest field
+ * may not do.
+ */
+/**
+ * The official SemVer 2.0.0 grammar (semver.org, "Backus–Naur Form Grammar for
+ * Valid SemVer Versions"), transcribed. Kept verbatim rather than loosened: a
+ * home-grown `\d+\.\d+\.\d+` would accept `01.2.3` and reject `1.0.0-rc.1`,
+ * which is wrong in both directions.
+ */
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+/** Whether `value` is a SemVer 2.0.0 version string. Total: any input, no throw. */
+export function isSemverVersion(value) {
+    return typeof value === 'string' && SEMVER.test(value);
+}
+/**
+ * The sentence a bad version gets. Names the value, the grammar, and the
+ * specific mistake when the shape identifies one — a refusal that only says
+ * "invalid" makes the author guess which half was wrong.
+ *
+ * @param callSite - the API the author called, e.g. `defineAgentRecipe`.
+ */
+export function versionRefusal(callSite, value) {
+    const shown = typeof value === 'string' ? `'${value}'` : `${typeof value}`;
+    return (`${callSite}: version ${shown} is not a version. A recipe's version must be SemVer 2.0.0 ` +
+        `— three dot-separated numbers, optionally a prerelease and build ('1.2.0', '2.0.0-rc.1', ` +
+        `'1.0.0+build.5').\n\n` +
+        `${diagnose(value)}\n\n` +
+        `Nothing is padded or stripped for you: the version is stamped on the run manifest, where ` +
+        `it is the field two runs are grouped by, and a value the author never wrote would group ` +
+        `runs that are not the same composition.`);
+}
+/** The specific mistake, when the shape names one. Falls back to the general rule. */
+function diagnose(value) {
+    if (typeof value !== 'string') {
+        return `A version is a string; this was ${value === null ? 'null' : typeof value}.`;
+    }
+    if (value.trim() === '')
+        return 'This one is empty.';
+    if (/^v/i.test(value)) {
+        return `Drop the leading '${value[0] ?? 'v'}' — SemVer carries no prefix ('1.2.0', not '${value}').`;
+    }
+    if (/^\d+\.\d+$/.test(value)) {
+        return (`This has two parts; SemVer has three. Did you mean '${value}.0'? Write it out — ` +
+            `'${value}' and '${value}.0' would be two labels for one composition.`);
+    }
+    if (/^\d+$/.test(value)) {
+        return `This is one number. Did you mean '${value}.0.0'?`;
+    }
+    if (/^[~^><=]/.test(value) || /\bx\b|\*/.test(value)) {
+        return (`This is a RANGE, not a version. A range names whatever happens to be installed, so the ` +
+            `manifest row would describe a different composition each week. Write the version this ` +
+            `recipe IS.`);
+    }
+    if (/^0\d|\.0\d/.test(value)) {
+        return `Numeric parts carry no leading zeros ('1.2.0', not '01.02.00').`;
+    }
+    return `Neither the numbers, the prerelease nor the build metadata matched the grammar.`;
+}
+//# sourceMappingURL=version.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../src/recipes/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,GACV,qLAAqL,CAAC;AAExL,oFAAoF;AACpF,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,KAAc;IAC7D,MAAM,KAAK,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,EAAE,CAAC;IAC3E,OAAO,CACL,GAAG,QAAQ,aAAa,KAAK,6DAA6D;QAC1F,2FAA2F;QAC3F,uBAAuB;QACvB,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM;QACxB,2FAA2F;QAC3F,0FAA0F;QAC1F,yCAAyC,CAC1C,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,mCAAmC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,GAAG,CAAC;IACtF,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,oBAAoB,CAAC;IACrD,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,qBACL,KAAK,CAAC,CAAC,CAAC,IAAI,GACd,+CAA+C,KAAK,KAAK,CAAC;IAC5D,CAAC;IACD,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,CACL,uDAAuD,KAAK,sBAAsB;YAClF,IAAI,KAAK,UAAU,KAAK,8CAA8C,CACvE,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,qCAAqC,KAAK,QAAQ,CAAC;IAC5D,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO,CACL,yFAAyF;YACzF,wFAAwF;YACxF,YAAY,CACb,CAAC;IACJ,CAAC;IACD,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,iEAAiE,CAAC;IAC3E,CAAC;IACD,OAAO,iFAAiF,CAAC;AAC3F,CAAC"}