agentfootprint 10.2.0 → 10.3.1

package/dist/types/injection-engine/constrainedEnumPick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constrainedEnumPick.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/constrainedEnumPick.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,WAAW,EAIZ,MAAM,+BAA+B,CAAC;AAIvC,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;+EAC2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B;6EACyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;gEAC4D;IAC5D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;QAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC,CAAC;IACH,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;4DACwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,wEAAwE;AACxE,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,0BAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAI1F;AAsED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAG7F"}

package/dist/types/injection-engine/devWarn.d.ts

@@ -0,0 +1,48 @@
+/**
+ * devWarn — the dev-warning SEAM for the pure skill-graph core (9.34.0).
+ *
+ * THE PROBLEM IT SOLVES. `skillGraph.ts` and `skillIntent.ts` print dev-mode
+ * warnings (a throwing matcher, a check-up with problems, a leaf set that did
+ * not fire exactly once). Those warnings were gated on `isDevMode()` imported
+ * from `footprintjs` — a real dependency on the flowchart engine, inside the
+ * two files whose whole point is that they do not depend on one. footprintjs's
+ * dev flag is a module-private boolean toggled by `enableDevMode()`, so the
+ * pure core cannot read it without importing the engine.
+ *
+ * THE SEAM. The pure core asks a READER it was handed. The default reader
+ * says "not dev mode", so a pure-core-only host is silent until it opts in.
+ * agentfootprint's own host binds the reader to footprintjs's `isDevMode`
+ * (see `devWarnHost.ts`, side-effect-imported by the injection-engine
+ * barrel), so every warning in this package behaves exactly as it did — same
+ * text, same gate, same `enableDevMode()` switch.
+ *
+ * (Precedent: footprintjs's own `capture/envelope.ts` dev-warn seam — the
+ * pure module stays pure, the tier that owns the flag binds the warner.)
+ *
+ * Zone: PURE CORE. Pinned by
+ * `test/injection-engine/skill-graph-fence.test.ts`.
+ */
+/** Answers "should dev-time warnings print?". */
+export type DevModeReader = () => boolean;
+/**
+ * Bind the dev-mode reader the pure core consults.
+ *
+ * agentfootprint calls this for you — importing anything from
+ * `agentfootprint/context` (or the main entry) binds it to footprintjs's
+ * `isDevMode`, so `enableDevMode()` keeps switching skill-graph warnings on
+ * exactly as before.
+ *
+ * A host running the graph through `agentfootprint/skill-graph` alone gets
+ * NO warnings until it calls this — that door deliberately loads no engine,
+ * and a warning gate is not worth an import of one.
+ *
+ * @example turn skill-graph dev warnings on in a foreign host
+ *   import { useSkillGraphDevMode } from 'agentfootprint/skill-graph';
+ *   useSkillGraphDevMode(() => process.env.NODE_ENV !== 'production');
+ */
+export declare function useSkillGraphDevMode(read: DevModeReader | undefined): void;
+/** Is dev mode on, per the bound reader? The gate the hot paths check. */
+export declare function devMode(): boolean;
+/** Print `message` to the console when dev mode is on. Never throws. */
+export declare function devWarn(message: string): void;
+//# sourceMappingURL=devWarn.d.ts.map

package/dist/types/injection-engine/devWarn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devWarn.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/devWarn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC;AAM1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAE1E;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI7C"}

package/dist/types/injection-engine/devWarnHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devWarnHost.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/devWarnHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/types/injection-engine/entryScorer.d.ts

@@ -0,0 +1,112 @@
+/**
+ * EntryScorer — the pluggable STRATEGY for ranking a skill graph's entry
+ * candidates by relevance to the user's message.
+ *
+ * `skillGraph().entryBy(scorer)` selects a strategy; the agent's PickEntry stage
+ * runs it ONCE per turn (off the hot loop) and starts the cursor at the winner.
+ * Two built-ins ship:
+ *   • `keywordScorer()`      — no dependency, no model call: word overlap between
+ *     the message and each skill's `description`. The zero-config way to route.
+ *   • `embeddingScorer(e)`   — semantic: cosine similarity of embeddings (needs an
+ *     Embedder). `.entryByRelevance(embedder)` is sugar for this.
+ * Bring your own by implementing `EntryScorer`.
+ *
+ * The scorer OWNS both the surfaced `relevance` % AND the `chosen` winner, so the
+ * explanation and the decision can never disagree (softmax is order-preserving, so
+ * argmax-score == argmax-relevance).
+ */
+import type { Embedder } from '../memory/embedding/types.js';
+import type { IntentScorer } from './intentScorer.js';
+/** One entry candidate's relevance to the user's message. */
+export interface EntryScore {
+    /** The entry skill id. */
+    readonly id: string;
+    /** Raw, strategy-specific score — cosine for `embedding`, word-overlap for
+     *  `keyword`. Higher = more relevant. Not normalized across strategies. */
+    readonly score: number;
+    /** Softmax share across candidates, 0..1 — the surfaced "Why this skill?" %. */
+    readonly relevance: number;
+}
+/** Result of scoring the entries — the picked entry, the full ranking, and which
+ *  scorer produced it. */
+export interface EntryScoring {
+    /** The scorer's `name` (e.g. `'keyword'`, `'embedding'`) — surfaced so a lens /
+     *  the "Why this skill?" panel can say HOW the entry was chosen. */
+    readonly scorer: string;
+    /** Winning entry id (highest `score`), or undefined if no candidate. */
+    readonly chosen: string | undefined;
+    /** Every scored candidate, in declaration order. */
+    readonly ranked: readonly EntryScore[];
+}
+/** A candidate the scorer ranks — its id + the text it's matched on (the skill's
+ *  `description`). */
+export interface EntryCandidate {
+    readonly id: string;
+    readonly description: string;
+}
+/** What a scorer receives: the user's message + the candidates to rank. */
+export interface EntryScorerInput {
+    readonly userMessage: string;
+    readonly candidates: readonly EntryCandidate[];
+}
+/**
+ * A strategy for ranking entry candidates. Pure given its inputs; may be async (an
+ * embedder makes network calls). Runs ONCE per turn off the hot loop, so cost here
+ * never touches the ReAct inner loop.
+ */
+export interface EntryScorer {
+    /** Short, stable name — shown in the lens / "Why this skill?" panel + any
+     *  strategy picker. */
+    readonly name: string;
+    score(input: EntryScorerInput, signal?: AbortSignal): Promise<EntryScoring> | EntryScoring;
+}
+/**
+ * Shared finisher: raw scores → `EntryScoring`. Softmax turns the (sanitized) raw
+ * scores into a `relevance` share (sums to 1); the winner is the argmax with
+ * declaration order breaking ties. Because softmax is order-preserving over the
+ * sanitized scores, the WINNER is always the argmax `relevance` — the surfaced %
+ * and the pick can never disagree.
+ *
+ * `EntryScorer` is a public, consumer-implementable interface, so a third-party
+ * scorer might return `NaN` / `±Infinity`. We sanitize those to `-Infinity` for BOTH
+ * the softmax input AND the winner pick, so a non-finite score can never silently win
+ * (`NaN > x` is always false — a leading `NaN` would otherwise seed-and-keep a naive
+ * reduce) and the softmax stays well-defined. The raw (possibly non-finite) score is
+ * still surfaced on `EntryScore.score` for honest debugging.
+ */
+export declare function rankEntries(scorerName: string, candidates: readonly EntryCandidate[], rawScores: readonly number[]): EntryScoring;
+/**
+ * keywordScorer — rank by word overlap between the message and each description.
+ * No embedder, no model call, deterministic. Scores the set-cosine of lowercased
+ * word tokens (length-normalized so a long description can't win on sheer size),
+ * minus a small stop-word list. The zero-config router: good enough when skill
+ * descriptions use the words a user would.
+ *
+ * ALSO an {@link IntentScorer} (SG-C): handed a candidates array as the second
+ * argument it scores the message's set-cosine against each intent's sentence +
+ * examples, and declares `floor: 0` — zero token overlap IS honestly "did not
+ * match at all", so this scorer can say *unmatched*. One factory, one name,
+ * two arities; existing `EntryScorer` callers are byte-unaffected.
+ */
+export declare function keywordScorer(options?: {
+    readonly stopWords?: readonly string[];
+}): EntryScorer & IntentScorer;
+/**
+ * embeddingScorer — rank by SEMANTIC similarity. Embeds the message + each
+ * description and cosine-scores them. Needs an `Embedder` (a model call per text);
+ * runs once per turn off the hot loop. `.entryByRelevance(embedder)` is sugar for
+ * `.entryBy(embeddingScorer(embedder))`.
+ *
+ * ALSO an {@link IntentScorer} (SG-C): handed a candidates array it embeds the
+ * message + one text per candidate (the intent sentence with its examples) and
+ * cosine-scores them. **No floor unless you declare one** (`{ floor }`): an
+ * absolute embedding threshold is a lie by default — measured in the field,
+ * real intent clusters separate by single-digit percentages of cosine, so a
+ * built-in cutoff would flip between "unmatched" and "decisive" on noise.
+ * Without a floor this scorer can say *stay*, *move* or *near-tie*, never
+ * *unmatched* — the verdict table documents that honestly.
+ */
+export declare function embeddingScorer(embedder: Embedder, options?: {
+    readonly floor?: number;
+}): EntryScorer & IntentScorer;
+//# sourceMappingURL=entryScorer.d.ts.map

package/dist/types/injection-engine/entryScorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entryScorer.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/entryScorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAG7D,OAAO,KAAK,EAGV,YAAY,EAEb,MAAM,mBAAmB,CAAC;AAE3B,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;+EAC2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;0BAC0B;AAC1B,MAAM,WAAW,YAAY;IAC3B;wEACoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;CACxC;AAED;sBACsB;AACtB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;2BACuB;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;CAC5F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,SAAS,cAAc,EAAE,EACrC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,YAAY,CAcd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,OAAO,GAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACvD,WAAW,GAAG,YAAY,CA0B5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,WAAW,GAAG,YAAY,CAyC5B"}

package/dist/types/injection-engine/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../../src/injection-engine/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAMnF,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,GAAG,EAAE,gBAAgB,GACpB,mBAAmB,CA+GrB"}

package/dist/types/injection-engine/factories/defineFact.d.ts

@@ -0,0 +1,85 @@
+/**
+ * defineFact — sugar for context-style Injections (data, not behavior).
+ *
+ * Use for developer-supplied facts the LLM should see in addition to
+ * user messages and tool results. Examples: user profile, env info,
+ * computed conversation summary, cached config, current time. Distinct
+ * from Skills (LLM-activated guidance) and Steering (always-on rules)
+ * in INTENT — they share the engine.
+ *
+ * Produces an `Injection` with:
+ *   - flavor: `'fact'`
+ *   - trigger: configurable (default `'always'`)
+ *   - inject: `systemPrompt` (default), or `messages` with a declared role
+ *
+ * @example
+ *   const userProfile = defineFact({
+ *     id: 'user-profile',
+ *     data: `Name: ${user.name}, Plan: ${user.plan}, Joined: ${user.joinedAt}`,
+ *   });
+ *
+ *   const turnTime = defineFact({
+ *     id: 'turn-time',
+ *     data: `Current time: ${new Date().toISOString()}`,
+ *   });
+ */
+import type { WireRole } from '../../provider-contract/types.js';
+import type { Injection, InjectionContext } from '../types.js';
+import type { CachePolicy } from '../../cache/types.js';
+interface DefineFactBase {
+    readonly id: string;
+    readonly description?: string;
+    /** The fact (data string) to inject. */
+    readonly data: string;
+    /**
+     * Trigger control. Defaults to always-on. For conditional facts
+     * (e.g., "only show user profile after iteration 3"), pass a
+     * predicate via `activeWhen`.
+     */
+    readonly activeWhen?: (ctx: InjectionContext) => boolean;
+    /**
+     * Cache policy for this fact injection. Defaults to `'always'` —
+     * facts are typically static data the LLM should always have in mind.
+     * Override with `'never'` for facts containing volatile content
+     * (e.g., a `Current time:` fact); use `{ until }` for time-bounded
+     * facts.
+     */
+    readonly cache?: CachePolicy;
+}
+/**
+ * `slot` and `role` are ONE decision, so the type makes them one choice.
+ *
+ * `slot: 'messages'` requires a `role` and there is deliberately no default:
+ * who appears to speak is a meaning the app owns. (Before 7.19.1 the option
+ * existed with `role` defaulting to `'system'` — a default that reached the
+ * model on OpenAI-family providers and vanished on Anthropic-family ones.
+ * Now the role is stated, and a provider that cannot carry it refuses at run
+ * start by name.) `slot: 'system-prompt'` forbids `role`, because there is no
+ * role in a system prompt to choose.
+ */
+export type DefineFactOptions = DefineFactBase & ({
+    /** The default. The one placement every provider delivers. */
+    readonly slot?: 'system-prompt';
+    readonly role?: never;
+} | {
+    /**
+     * Deliver the fact into the conversation itself — it enters
+     * `scope.history` at the injection-engine boundary, so the window
+     * strategies, the slots and the wire all see the same past.
+     * Placed at the END of the window; if its role would collide with
+     * the turn already there, delivery defers to the next boundary and
+     * says so on `messagesDelivery.deferred`.
+     */
+    readonly slot: 'messages';
+    /**
+     * Who appears to say it. Required — no default. Refused at run start
+     * when the attached provider does not carry it inside `messages`
+     * (the Anthropic family drops `'system'` there; the OpenAI family
+     * carries it). `'tool'` is refused outright: a tool message answers a
+     * specific call, and an injection has no call to answer.
+     */
+    readonly role: WireRole;
+});
+export declare function defineFact(opts: DefineFactOptions): Injection;
+export {};
+//# sourceMappingURL=defineFact.d.ts.map

package/dist/types/injection-engine/factories/defineFact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineFact.d.ts","sourceRoot":"","sources":["../../../../src/injection-engine/factories/defineFact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAoB,MAAM,aAAa,CAAC;AAGjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,UAAU,cAAc;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACzD;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAC5C,CACI;IACE,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;CACvB,GACD;IACE;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB,CACJ,CAAC;AAEJ,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CA6C7D"}

package/dist/types/injection-engine/factories/defineInjection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineInjection.d.ts","sourceRoot":"","sources":["../../../../src/injection-engine/factories/defineInjection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAqB,KAAK,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjF,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAC9B,CAAC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GAAG,wBAAwB,CAAC,GACpD,CAAC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,kBAAkB,CAAC,GACxC,CAAC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG,qBAAqB,CAAC,GAC9C,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,iBAAiB,CAAC,CAAC;AAE3C,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAE7D,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,SAAS,CAsBvE"}

package/dist/types/injection-engine/factories/defineInstruction.d.ts

@@ -0,0 +1,139 @@
+/**
+ * defineInstruction — sugar for rule-based system-prompt Injections.
+ *
+ * The most flexible Instruction-style flavor: a predicate decides
+ * activation each iteration. Use for "if condition X is true, give
+ * the LLM this guidance". Compared to:
+ *   - Steering (always-on, no predicate)
+ *   - Skill (LLM-activated via `read_skill`)
+ *   - on-tool-return (specific tool just ran — Dynamic ReAct)
+ *
+ * Produces an `Injection` with:
+ *   - flavor: `'instructions'`
+ *   - trigger: `{ kind: 'rule', activeWhen }` (or `'always'` if omitted)
+ *   - inject: `{ systemPrompt: prompt }`, or `{ messages: [{ role, content }] }`
+ *     when `slot: 'messages'` names the role it speaks as
+ *
+ * @example
+ *   const calmTone = defineInstruction({
+ *     id: 'calm-tone',
+ *     description: 'Use a calm, empathetic tone with frustrated users.',
+ *     activeWhen: (ctx) => /upset|angry|frustrated/.test(ctx.userMessage),
+ *     prompt: 'Acknowledge feelings before facts. Avoid corporate jargon.',
+ *   });
+ *
+ *   const piiAfterRedact = defineInstruction({
+ *     id: 'pii-after-redact',
+ *     activeWhen: (ctx) => ctx.lastToolResult?.toolName === 'redact_pii',
+ *     prompt: 'PII has been redacted. Do not include emails or phone numbers.',
+ *   });
+ */
+import type { WireRole } from '../../provider-contract/types.js';
+import type { Injection, InjectionContext } from '../types.js';
+import type { CachePolicy } from '../../cache/types.js';
+interface DefineInstructionBase {
+    readonly id: string;
+    readonly description?: string;
+    /**
+     * Predicate to decide activation. Synchronous; side-effect free.
+     * If omitted, the instruction is always active (effectively a
+     * Steering doc, but tagged with `'instructions'` flavor for
+     * narrative semantics — use `defineSteering` for clearer intent).
+     * Predicates that throw are skipped (fail-open) and reported via
+     * `agentfootprint.context.evaluated`.
+     */
+    readonly activeWhen?: (ctx: InjectionContext) => boolean;
+    /**
+     * Cache policy for this instruction. Defaults to `'never'` —
+     * instructions are typically rule-based (volatile per-iter
+     * `activeWhen` predicates, on-tool-return reminders). Override to
+     * `'always'` only for instructions you know are stable per-turn
+     * (e.g., a static safety rule wrapped as `defineInstruction` for
+     * narrative tagging — though `defineSteering` is the cleaner choice
+     * for that case).
+     */
+    readonly cache?: CachePolicy;
+}
+/**
+ * `slot` and `role` are ONE decision, so the type makes them one choice —
+ * see {@link DefineFactOptions} for the full reasoning. In short:
+ * `slot: 'messages'` requires a `role` with no default (who appears to speak
+ * is the app's meaning to set), and `slot: 'system-prompt'` forbids one.
+ */
+/**
+ * The instruction's words — a fixed string, or a template that names run-time
+ * facts. Exactly one, because they are the same decision spelled two ways and
+ * a definition carrying both would leave the library picking one.
+ */
+export type DefineInstructionWords = {
+    /** Instruction text, exactly as the model will read it. */
+    readonly prompt: string;
+    readonly promptTemplate?: never;
+} | {
+    readonly prompt?: never;
+    /**
+     * Instruction text with named run-time facts in it (9.57.0), rendered
+     * fresh on every action:
+     *
+     * ```ts
+     * promptTemplate:
+     *   'You are on action {{action}} of {{actionBudget}}; ' +
+     *   '{{actionsRemaining}} remain. Finish what you have rather than start something new.',
+     * ```
+     *
+     * The vocabulary is CLOSED and has three words — `{{action}}`,
+     * `{{actionBudget}}`, `{{actionsRemaining}}` — and a name outside it is
+     * refused here, at define time, rather than rendering as a literal in
+     * front of the model. It is closed rather than a `(ctx) => string`
+     * because a function makes ABSENCE the author's problem: given one, an
+     * author writes `${ctx.maxIterations}` and ships "23 of undefined", or
+     * writes `?? 0` and ships a fabricated denominator nothing can tell
+     * from a real zero. With named slots the library owns absence and
+     * applies one rule — if any named fact is unavailable the whole
+     * instruction is skipped, by name, on the record.
+     *
+     * Two things a template may not be, both refused at define time:
+     * `slot: 'messages'` (the delivery ledger keys by content, so a
+     * re-render would deliver a NEW message on every action), and any
+     * `cache` other than `'never'` (a marker asserting a stable prefix
+     * through bytes that change every call is a guaranteed miss plus the
+     * cache-write premium, with the trace claiming a stable prefix).
+     *
+     * Declare templated instructions LAST: a never-cacheable injection
+     * truncates the cached prefix at its declaration position.
+     */
+    readonly promptTemplate: string;
+};
+export type DefineInstructionOptions = DefineInstructionBase & DefineInstructionWords & ({
+    /**
+     * The default. Appended to the system prompt — the one placement
+     * every provider delivers. An `on-tool-return` instruction already
+     * lands on exactly the turn it matters; this is a system prompt that
+     * says it on that one turn, rather than on every turn.
+     */
+    readonly slot?: 'system-prompt';
+    readonly role?: never;
+} | {
+    /**
+     * Deliver the instruction into the conversation itself — it enters
+     * `scope.history` at the injection-engine boundary, at the END of the
+     * window, so the model reads it at the recency this option is
+     * reaching for. If its role would collide with the turn already at
+     * the end, delivery defers to the next boundary and says so on
+     * `messagesDelivery.deferred` rather than reordering anything.
+     *
+     * In a tool-using loop the window ends on the user's turn or on tool
+     * results, so a `'user'` role typically never gets a slot. Use
+     * `'assistant'`, use `'system'` on a provider that carries it, or
+     * return the words from the tool whose result they are about.
+     */
+    readonly slot: 'messages';
+    /**
+     * Who appears to say it. Required — no default. Refused at run start
+     * when the attached provider does not carry it inside `messages`.
+     */
+    readonly role: WireRole;
+});
+export declare function defineInstruction(opts: DefineInstructionOptions): Injection;
+export {};
+//# sourceMappingURL=defineInstruction.d.ts.map

package/dist/types/injection-engine/factories/defineInstruction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineInstruction.d.ts","sourceRoot":"","sources":["../../../../src/injection-engine/factories/defineInstruction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAoB,MAAM,aAAa,CAAC;AAIjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACzD;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;GAKG;AACH;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IACE,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC;CACjC,GACD;IACE,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC,CAAC;AAEN,MAAM,MAAM,wBAAwB,GAAG,qBAAqB,GAC1D,sBAAsB,GACtB,CACI;IACE;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;CACvB,GACD;IACE;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB,CACJ,CAAC;AAEJ,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,SAAS,CA4E3E"}

package/dist/types/injection-engine/factories/defineMenuHint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineMenuHint.d.ts","sourceRoot":"","sources":["../../../../src/injection-engine/factories/defineMenuHint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB;iFAC6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,iBAA2B,CAAC;AAQ/D,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,SAAS,CAevE"}

package/dist/types/injection-engine/factories/defineRelevanceHint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineRelevanceHint.d.ts","sourceRoot":"","sources":["../../../../src/injection-engine/factories/defineRelevanceHint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AAE/D,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,+BAA+B,oBAA8B,CAAC;AAS3E,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,SAAS,CAoBjF"}