agentfootprint 9.47.0 → 9.49.0

package/dist/esm/lib/bug-report/envelope.js

@@ -0,0 +1,74 @@
+/**
+ * stampConversation — put the bundle's evidence in the archive contract, or
+ * say in one sentence why it could not be.
+ *
+ * The repo has ONE archive contract (`RecordingEnvelope`) and several
+ * presentations over it. This bundle used to be an exception: it packed a bare
+ * `recording.json` plus an `environment.json` that repeated the producer facts
+ * the envelope already stamps, so the same two versions were written by two
+ * different pieces of code with no relationship between them. This is the fold
+ * — the envelope is BUILT here, never re-implemented, so every rule it enforces
+ * (identity is never invented, `droppedEvents` is proven or refused, an
+ * incomplete recording gets no `endedAt`) arrives whole.
+ *
+ * ## Why a refusal is a return value here, not a throw
+ *
+ * `persistRecording` throws when a run fact is indeterminate, and it is right
+ * to: its caller asked for an ARCHIVE, and an archive stamped with a guess is
+ * worse than none. A bug report's caller asked for something else — the
+ * evidence, in a zip, so a maintainer can open it. Throwing would leave that
+ * person with no bundle at all because the library could not name a start time.
+ *
+ * So the refusal travels instead of stopping the export: this returns the
+ * REASON, the bundle carries the bare recording under its own honest name, and
+ * the manifest states which fact was missing and the one line that supplies it.
+ * Nothing is stamped that was not known — which is the rule the throw exists to
+ * keep — and the report still gets filed.
+ *
+ * @internal Not a public export; `exportBugReport` is the door.
+ */
+import { buildRecordingEnvelope, IndeterminateRunFactError, } from '../../recorders/observability/recordingEnvelope.js';
+/**
+ * Envelope every recording of one conversation.
+ *
+ * @param sources  the conversation's recordings, in order, each with whether it
+ *                 can prove its own drop count.
+ * @param facts    what the reporter stated. `undefined` — the default, since
+ *                 `run` is optional on both entry points — is itself a refusal
+ *                 reason, and a named one.
+ */
+export function stampConversation(sources, facts) {
+    if (facts === undefined || typeof facts.complete !== 'boolean') {
+        return {
+            field: 'complete',
+            refusal: 'run.complete was not stated. Nothing in a frozen recording says whether it captured ' +
+                'the run through to its end — a crash-handler snapshot and a finished run look ' +
+                'identical — so the library asks rather than guessing, and defaulting it would make ' +
+                'every partial recording claim to be whole. Pass run: { complete: true } (or false) ' +
+                'to exportBugReport.',
+        };
+    }
+    const envelopes = [];
+    for (const entry of sources) {
+        try {
+            envelopes.push(buildRecordingEnvelope(entry.source, {
+                run: {
+                    complete: facts.complete,
+                    // A count the library can CHECK is never overridden by one it
+                    // cannot: a live handle knows what the cap discarded, so a stated
+                    // number is only offered for the sources that carry no count.
+                    ...(!entry.countsDrops &&
+                        facts.droppedEvents !== undefined && { droppedEvents: facts.droppedEvents }),
+                },
+            }));
+        }
+        catch (error) {
+            if (error instanceof IndeterminateRunFactError) {
+                return { refusal: error.message, field: error.field };
+            }
+            throw error;
+        }
+    }
+    return { envelopes };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/esm/lib/bug-report/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../../src/lib/bug-report/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACL,sBAAsB,EACtB,yBAAyB,GAG1B,MAAM,oDAAoD,CAAC;AA2C5D;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAkC,EAClC,KAAoC;IAEpC,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC/D,OAAO;YACL,KAAK,EAAE,UAAU;YACjB,OAAO,EACL,sFAAsF;gBACtF,gFAAgF;gBAChF,qFAAqF;gBACrF,qFAAqF;gBACrF,qBAAqB;SACxB,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAwB,EAAE,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,SAAS,CAAC,IAAI,CACZ,sBAAsB,CAAC,KAAK,CAAC,MAAM,EAAE;gBACnC,GAAG,EAAE;oBACH,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,8DAA8D;oBAC9D,kEAAkE;oBAClE,8DAA8D;oBAC9D,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW;wBACpB,KAAK,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC;iBAC/E;aACF,CAAC,CACH,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,yBAAyB,EAAE,CAAC;gBAC/C,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YACxD,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}

package/dist/esm/lib/bug-report/index.d.ts

@@ -10,5 +10,5 @@
  * promise this library wants to keep.
  */
 export { describeBugReport, exportBugReport } from './build.js';
-export type { BugReport, BugReportEnvironment, BugReportExcluded, BugReportFields, BugReportFile, BugReportFileSummary, BugReportInput, BugReportManifest, BugReportOversize, BugReportSource, BugReportUnit, DescribeBugReportOptions, ExportBugReportOptions, } from './types.js';
+export type { BugReport, BugReportEnvironment, BugReportExcluded, BugReportFields, BugReportFile, BugReportFileSummary, BugReportInput, BugReportManifest, BugReportOversize, BugReportRunFacts, BugReportSource, BugReportUnit, DescribeBugReportOptions, ExportBugReportOptions, } from './types.js';
 export type { Transcript, TranscriptStep, TranscriptTurn } from './transcript.js';

package/dist/esm/lib/bug-report/types.d.ts

@@ -70,6 +70,18 @@ export interface BugReportUnit {
     readonly runCount?: number;
     /** The hosting session id, when the runs carried one. */
     readonly sessionId?: string;
+    /**
+     * Conversation units only. `true` when this conversation's evidence rides as
+     * a `RecordingEnvelope` — the archive contract, with the recording under its
+     * `recording` field; `false` when the envelope's run facts were not available
+     * and it rides as the bare recording instead.
+     *
+     * Stated per unit rather than per bundle because a bundle can be mixed: a
+     * live `recordRun` handle proves its own dropped-event count and a bare
+     * `Recording` alongside it cannot, so one conversation can be stamped while
+     * its neighbour is not. The manifest's notes name the missing fact.
+     */
+    readonly enveloped?: boolean;
     /** Files this unit puts in the bundle (a `file` unit has exactly one). */
     readonly files: readonly string[];
 }
@@ -92,7 +104,15 @@ export interface BugReportExcluded {
     /** The unit ids that were offered and not included. */
     readonly unitIds: readonly string[];
 }
-/** Versions, and deliberately nothing that identifies a machine or a person. */
+/**
+ * Versions, and deliberately nothing that identifies a machine or a person.
+ *
+ * This is the MANIFEST's summary block — the one a consent dialog and the issue
+ * body print. The bundled `environment.json` is deliberately NARROWER: since
+ * the bundle carries a {@link BugReportManifest.manifestVersion} 2 envelope,
+ * the producer versions are stamped there (`envelope.json` → `producer`) and
+ * the file keeps only the host half. One archive fact, one stamping place.
+ */
 export interface BugReportEnvironment {
     /** This library's version, read from its own package manifest. */
     readonly agentfootprint: string;
@@ -106,6 +126,45 @@ export interface BugReportEnvironment {
     /** The reporting application's own version, when it told us. */
     readonly appVersion?: string;
 }
+/**
+ * The run facts an archive envelope needs and a frozen recording cannot supply.
+ *
+ * The bundle's evidence rides as a `RecordingEnvelope` — the one archive
+ * contract this repo has — and that envelope refuses to stamp a fact it had to
+ * guess. Two of its fields have no derivation:
+ *
+ *   `complete`       nothing in a frozen recording says whether it reached the
+ *                    run's end; a crash-handler snapshot and a finished run
+ *                    look identical. Stated, or the envelope is not built.
+ *   `droppedEvents`  only the live `recordRun` handle counts what the
+ *                    `maxEvents` cap discarded.
+ *
+ * Everything else the envelope needs — `runId`, `sessionId`, `principal`,
+ * `tenant`, `startedAt`, `endedAt` — is derived per recording from that
+ * recording's OWN events, and is deliberately not settable here: a bundle may
+ * carry several runs, and one run id stated once cannot be true of all of them.
+ */
+export interface BugReportRunFacts {
+    /**
+     * Did each recording in this bundle capture its run through to the end?
+     *
+     * Say `false` for a recording frozen from a crash handler, a timeout or
+     * mid-stream. Leave the whole `run` option off and the bundle still carries
+     * the evidence — as the bare recording, with the manifest stating in a note
+     * which fact was missing and how to supply it.
+     */
+    readonly complete: boolean;
+    /**
+     * Events lost to the recorder's `maxEvents` cap, for sources that cannot
+     * prove their own count.
+     *
+     * A live `recordRun` handle counts them, and that PROVEN count wins over
+     * anything stated here — a number the library can check is never overridden
+     * by a number it cannot. State this when the bundle is built from bare
+     * `Recording` objects, whose shape carries no count.
+     */
+    readonly droppedEvents?: number;
+}
 /** The oversize verdict, with hints that name real, droppable unit ids. */
 export interface BugReportOversize {
     readonly totalBytes: number;
@@ -122,7 +181,19 @@ export interface BugReportOversize {
  * the reporter's fields, and states the exclusions.
  */
 export interface BugReportManifest {
-    readonly manifestVersion: 1;
+    /**
+     * The BUNDLE LAYOUT version — bumped when the file set or this manifest's own
+     * shape changes, so a reader can tell which archive it is holding instead of
+     * inferring it from which names happen to be present.
+     *
+     *   1 — the evidence rode as a bare `recording.json`, and `environment.json`
+     *       repeated the producer versions the archive contract stamps.
+     *   2 — the evidence rides as `envelope.json`, a full `RecordingEnvelope`;
+     *       `environment.json` keeps only the host facts the envelope does not
+     *       hold. A conversation whose run facts could not be stamped falls back
+     *       to `recording.json` and the manifest says which fact was missing.
+     */
+    readonly manifestVersion: 2;
     /** ISO 8601, UTC. Also the timestamp stamped on every zip entry. */
     readonly createdAt: string;
     /** Present on an export manifest; absent on a description. */
@@ -198,9 +269,22 @@ export interface ExportBugReportOptions extends BugReportFields {
     readonly warnOverBytes?: number;
     /** Override the timestamp — the only thing that makes the zip deterministic. */
     readonly now?: Date;
+    /**
+     * The two run facts the archive envelope cannot derive. Supply them and the
+     * bundle's evidence rides as `envelope.json`; leave them off and it rides as
+     * the bare `recording.json`, with the manifest naming the missing fact.
+     */
+    readonly run?: BugReportRunFacts;
 }
-/** `describeBugReport` takes nothing but the input, and the same size dial. */
+/** `describeBugReport` takes nothing but the input, and the same dials. */
 export interface DescribeBugReportOptions {
     readonly warnOverBytes?: number;
     readonly now?: Date;
+    /**
+     * The same run facts {@link ExportBugReportOptions.run} takes — pass the same
+     * value to both calls. The offer measures the files the export will write, so
+     * stating the facts to one call and not the other would size the bundle from
+     * a different set of files than the one that leaves.
+     */
+    readonly run?: BugReportRunFacts;
 }

package/dist/esm/observe.d.ts

@@ -39,7 +39,9 @@ export { boundaryRecorder, BoundaryRecorder, type ActorArrow, type BoundaryAggre
 export { buildRunSteps, RunStepRecorder, runStepRecorder, type BuildRunStepsOptions, type RunStep, type RunStepGraph, type RunStepKind, type RunStepMeta, type RunStepRecorderOptions, type RunStepTransition, } from './recorders/observability/RunStepRecorder.js';
 export { attachFlowchart, buildStepGraph, buildStepGraphFromEvents, type StepGraph, type StepNode, type StepEdge, type SlotBoundary, type ContextInjection, type FlowchartOptions, type FlowchartHandle, } from './recorders/observability/FlowchartRecorder.js';
 export { recordRun, type Recording, type RecordRunOptions, type RunRecorder, } from './recorders/observability/recordRun.js';
-export { describeBugReport, exportBugReport, type BugReport, type BugReportEnvironment, type BugReportExcluded, type BugReportFields, type BugReportFile, type BugReportFileSummary, type BugReportInput, type BugReportManifest, type BugReportOversize, type BugReportSource, type BugReportUnit, type DescribeBugReportOptions, type ExportBugReportOptions, type Transcript, type TranscriptStep, type TranscriptTurn, } from './lib/bug-report/index.js';
+export { buildRecordingEnvelope, persistRecording, FULL_PRIVACY_POLICY_ID, RECORDING_ENVELOPE_FORMAT, IndeterminateRunFactError, UnsupportedPrivacyModeError, type BuildRecordingEnvelopeOptions, type PersistRecordingOptions, type RecordingConfiguration, type RecordingEnvelope, type RecordingPrivacy, type RecordingPrivacyMode, type RecordingProducer, type RecordingRun, type RecordingRunFacts, type RecordingSink, type RecordingSource, type RecordingTimestamp, } from './recorders/observability/recordingEnvelope.js';
+export { fileRecordingSink, recordingFileName, UnsafeRecordingIdError, type FileRecordingSinkOptions, } from './recorders/observability/fileRecordingSink.js';
+export { describeBugReport, exportBugReport, type BugReport, type BugReportEnvironment, type BugReportExcluded, type BugReportFields, type BugReportFile, type BugReportFileSummary, type BugReportInput, type BugReportManifest, type BugReportOversize, type BugReportRunFacts, type BugReportSource, type BugReportUnit, type DescribeBugReportOptions, type ExportBugReportOptions, type Transcript, type TranscriptStep, type TranscriptTurn, } from './lib/bug-report/index.js';
 export { summarizeEmbeddings, summarizeVector, type EmbeddingSummary, } from './recorders/observability/embeddingSummary.js';
 export { serializeTrace, redactContent, traceToStepGraph, type Trace, type TraceSummary, type TraceRedaction, type SerializeTraceOptions, } from './recorders/observability/trace.js';
 export { attachLocalObservability, type LocalObservabilityHandle, type LocalObservabilityOptions, } from './recorders/observability/localObservability.js';

package/dist/esm/observe.js

@@ -45,11 +45,29 @@ export { attachFlowchart, buildStepGraph, buildStepGraphFromEvents, } from './re
 // which is the shape the UIs consume (lens's `observeRecording`) and the one
 // every integration used to assemble by hand, each missing a different piece.
 export { recordRun, } from './recorders/observability/recordRun.js';
+// The recording ENVELOPE — the versioned contract that makes a recording
+// archivable. `recordRun` freezes a run; this states which run it is, how much
+// of it this is, who produced it and under what privacy policy, so a saved run
+// can be filed, attached to a bug report, or read by an analysis tool without
+// every consumer inventing its own wrapper. Every field is derived from the
+// run's own events or stated by the caller — never guessed.
+export { buildRecordingEnvelope, persistRecording, FULL_PRIVACY_POLICY_ID, RECORDING_ENVELOPE_FORMAT, IndeterminateRunFactError, UnsupportedPrivacyModeError, } from './recorders/observability/recordingEnvelope.js';
+// The reference sink: one archived run per JSON file, written atomically
+// (tmp + rename) so a crash never leaves a half-parsed archive. The file name
+// derives from the run id, which makes it a key — hence the asserted safe
+// charset and `UnsafeRecordingIdError` rather than a hopeful `${runId}.json`.
+export { fileRecordingSink, recordingFileName, UnsafeRecordingIdError, } from './recorders/observability/fileRecordingSink.js';
 // exportBugReport — a bug report IS the evidence. `describeBugReport` measures
 // the run first (selectable units, sizes, the redacted keys by NAME) so a human
 // can consent to exactly what leaves; `exportBugReport` bundles the units they
 // kept as named files plus a real (stored) zip. `githubBugReporter` — in this
 // same door, from the providers barrel — files that bundle.
+//
+// The evidence in that zip is a RecordingEnvelope (bundle layout 2), built by
+// the same `buildRecordingEnvelope` above rather than a second wrapper — so the
+// producer facts are stamped once. `BugReportRunFacts` is the pair the envelope
+// cannot derive; without it the bundle still ships, as the bare recording, with
+// the manifest naming the fact that was missing.
 export { describeBugReport, exportBugReport, } from './lib/bug-report/index.js';
 // What a recording keeps of a vector: `{ dims, norm }`, not the bytes (8.20.0).
 // Applied by BoundaryRecorder and recordRun unless `recordEmbeddings: true`;

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