agentfootprint 10.3.0 → 10.4.0

package/dist/injection-engine/factories/defineInstruction.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * 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.',
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineInstruction = void 0;
+const messagesSlotRefusal_js_1 = require("../messagesSlotRefusal.js");
+const promptTemplate_js_1 = require("../promptTemplate.js");
+const applyCachePolicy_js_1 = require("../../cache/applyCachePolicy.js");
+function defineInstruction(opts) {
+    if (!opts.id || opts.id.trim().length === 0) {
+        throw new Error('defineInstruction: `id` is required and must be non-empty.');
+    }
+    const words = opts;
+    if (words.prompt !== undefined && words.promptTemplate !== undefined) {
+        throw new Error(`defineInstruction('${opts.id}'): pass \`prompt\` OR \`promptTemplate\`, not both. ` +
+            `They are the same decision spelled two ways, and the library will not pick one for you.`);
+    }
+    const template = words.promptTemplate;
+    const text = template ?? words.prompt;
+    if (!text || text.length === 0) {
+        throw new Error(`defineInstruction(${opts.id}): \`prompt\` is required — or \`promptTemplate\`, when ` +
+            `the words name a run-time fact (${promptTemplate_js_1.TEMPLATE_FACTS.map((f) => `{{${f}}}`).join(', ')}).`);
+    }
+    // A template is refused HERE for everything it can be refused for, because
+    // everything below this line happens on somebody's paid run.
+    const templated = template !== undefined && (0, promptTemplate_js_1.isTemplate)(template);
+    if (template !== undefined)
+        (0, promptTemplate_js_1.assertKnownFacts)(template, `defineInstruction('${opts.id}')`);
+    // Refused at run time as well as in the type, read through a widened view —
+    // see defineFact for why the widening is deliberate.
+    const raw = opts;
+    const toMessages = raw.slot === 'messages';
+    if (toMessages && !raw.role) {
+        throw new Error(`defineInstruction('${opts.id}'): \`slot: 'messages'\` requires a \`role\` — ` +
+            `'user', 'assistant', or 'system' on a provider that carries it. There is no ` +
+            `default: who appears to speak is a meaning your app owns, not one the library picks.`);
+    }
+    if (toMessages && raw.role === 'tool') {
+        throw new Error((0, messagesSlotRefusal_js_1.messagesToolRoleRefusal)(`defineInstruction('${opts.id}')`));
+    }
+    if (templated && toMessages) {
+        throw new Error(`defineInstruction('${opts.id}'): \`promptTemplate\` cannot target ` +
+            `\`slot: 'messages'\`. The messages slot delivers each piece ONCE per run, and its ` +
+            `ledger keys by the content itself — so a template that renders differently every ` +
+            `action would deliver a new message every action, for the whole run. Use the ` +
+            `system-prompt slot (the default), which is re-composed per action by design.`);
+    }
+    if (templated && opts.cache !== undefined && opts.cache !== 'never') {
+        throw new Error(`defineInstruction('${opts.id}'): \`promptTemplate\` cannot be cached ` +
+            `(\`cache: '${String(opts.cache)}'\`). A cache marker asserts a STABLE PREFIX, and ` +
+            `these bytes change on every action — you would pay the cache-write premium for a ` +
+            `guaranteed miss, and the trace would claim a stable prefix that never existed. ` +
+            `Leave \`cache\` unset, or say \`cache: 'never'\` out loud.`);
+    }
+    const trigger = opts.activeWhen
+        ? { kind: 'rule', activeWhen: opts.activeWhen }
+        : { kind: 'always' };
+    const inject = toMessages
+        ? { messages: [{ role: raw.role, content: text }] }
+        : { systemPrompt: text };
+    const cache = (0, applyCachePolicy_js_1.resolveCachePolicy)('instruction', opts.cache);
+    return Object.freeze({
+        id: opts.id,
+        ...(opts.description && { description: opts.description }),
+        flavor: 'instructions',
+        trigger,
+        inject,
+        // TOP-LEVEL, not `metadata` (9.57.0): at least one live path rebuilds
+        // `metadata` wholesale, and a lost marker means the literal
+        // `{{actionsRemaining}}` reaches the model — the exact class of failure
+        // this feature exists to prevent. Top-level fields survive every
+        // `{...injection}` spread in the repo.
+        ...(templated && { templated: true }),
+        metadata: Object.freeze({ cache }),
+    });
+}
+exports.defineInstruction = defineInstruction;
+//# sourceMappingURL=defineInstruction.js.map

package/dist/injection-engine/factories/defineInstruction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineInstruction.js","sourceRoot":"","sources":["../../../src/injection-engine/factories/defineInstruction.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAIH,sEAAoE;AACpE,4DAAoF;AACpF,yEAAqE;AAoHrE,SAAgB,iBAAiB,CAAC,IAA8B;IAC9D,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,KAAK,GAAG,IAAoD,CAAC;IACnE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,EAAE,uDAAuD;YAClF,yFAAyF,CAC5F,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,cAAc,CAAC;IACtC,MAAM,IAAI,GAAG,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC;IACtC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,CAAC,EAAE,0DAA0D;YACpF,mCAAmC,kCAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAC1F,CAAC;IACJ,CAAC;IACD,2EAA2E;IAC3E,6DAA6D;IAC7D,MAAM,SAAS,GAAG,QAAQ,KAAK,SAAS,IAAI,IAAA,8BAAU,EAAC,QAAQ,CAAC,CAAC;IACjE,IAAI,QAAQ,KAAK,SAAS;QAAE,IAAA,oCAAgB,EAAC,QAAQ,EAAE,sBAAsB,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1F,4EAA4E;IAC5E,qDAAqD;IACrD,MAAM,GAAG,GAAG,IAAwC,CAAC;IACrD,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;IAC3C,IAAI,UAAU,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,EAAE,iDAAiD;YAC5E,8EAA8E;YAC9E,sFAAsF,CACzF,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,IAAA,gDAAuB,EAAC,sBAAsB,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,EAAE,uCAAuC;YAClE,oFAAoF;YACpF,mFAAmF;YACnF,8EAA8E;YAC9E,8EAA8E,CACjF,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,EAAE,0CAA0C;YACrE,cAAc,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,oDAAoD;YACpF,mFAAmF;YACnF,iFAAiF;YACjF,4DAA4D,CAC/D,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU;QAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE;QACxD,CAAC,CAAC,EAAE,IAAI,EAAE,QAAiB,EAAE,CAAC;IAChC,MAAM,MAAM,GAAqB,UAAU;QACzC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAgB,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE;QAC/D,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAA,wCAAkB,EAAC,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1D,MAAM,EAAE,cAAuB;QAC/B,OAAO;QACP,MAAM;QACN,sEAAsE;QACtE,4DAA4D;QAC5D,wEAAwE;QACxE,iEAAiE;QACjE,uCAAuC;QACvC,GAAG,CAAC,SAAS,IAAI,EAAE,SAAS,EAAE,IAAa,EAAE,CAAC;QAC9C,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;KACnC,CAAyB,CAAC;AAC7B,CAAC;AA5ED,8CA4EC"}

package/dist/injection-engine/factories/defineMenuHint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineMenuHint.js","sourceRoot":"","sources":["../../../src/injection-engine/factories/defineMenuHint.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAYH;;;;;;GAMG;AACU,QAAA,sBAAsB,GAAG,eAAwB,CAAC;AAE/D,MAAM,YAAY,GAChB,yFAAyF;IACzF,0FAA0F;IAC1F,0FAA0F;IAC1F,wFAAwF,CAAC;AAE3F,SAAgB,cAAc,CAAC,UAA2B,EAAE;IAC1D,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,iBAAiB;QACnC,MAAM,EAAE,cAAc;QACtB,WAAW,EAAE,gEAAgE;QAC7E,OAAO,EAAE;YACP,IAAI,EAAE,MAAM;YACZ,yEAAyE;YACzE,wEAAwE;YACxE,kEAAkE;YAClE,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,KAAK,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,OAAO,KAAK,SAAS;SACjF;QACD,QAAQ,EAAE,EAAE,CAAC,8BAAsB,CAAC,EAAE,IAAI,EAAE;QAC5C,MAAM,EAAE,EAAE,YAAY,EAAE,OAAO,CAAC,IAAI,IAAI,YAAY,EAAE;KACvD,CAAC;AACJ,CAAC;AAfD,wCAeC"}

package/dist/injection-engine/factories/defineRelevanceHint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineRelevanceHint.js","sourceRoot":"","sources":["../../../src/injection-engine/factories/defineRelevanceHint.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAcH;;;;;;;;;;;;;GAaG;AACU,QAAA,+BAA+B,GAAG,kBAA2B,CAAC;AAE3E,sDAAsD;AACtD,SAAS,SAAS,CAAC,MAAuC,EAAE,SAAiB;IAC3E,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC,CAAC,CAAE,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC,SAAS,GAAG,SAAS,CAAC;AACjE,CAAC;AAED,SAAgB,mBAAmB,CAAC,UAAgC,EAAE;IACpE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5C,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,gBAAgB;QAClC,MAAM,EAAE,cAAc;QACtB,WAAW,EAAE,8EAA8E;QAC3F,OAAO,EAAE;YACP,IAAI,EAAE,MAAM;YACZ,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,KAAK,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC;SAClF;QACD,QAAQ,EAAE,EAAE,CAAC,uCAA+B,CAAC,EAAE,IAAI,EAAE;QACrD,MAAM,EAAE;YACN,YAAY,EACV,sFAAsF;gBACtF,iFAAiF;gBACjF,sFAAsF;gBACtF,uFAAuF;gBACvF,uBAAuB;SAC1B;KACF,CAAC;AACJ,CAAC;AApBD,kDAoBC"}

package/dist/injection-engine/factories/defineSkill.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * defineSkill — sugar for LLM-activated Injections that target both
+ * system-prompt + tools.
+ *
+ * A Skill is a bundle of (1) a body of guidance and (2) optionally some
+ * tools. The LLM decides when a Skill is needed by calling a designated
+ * activation tool — by default `read_skill(<id>)`.
+ *
+ * Activation is about the BODY. A Skill's tools are registered up front
+ * and callable from iteration 1 unless the Skill sets
+ * `autoActivate: 'currentSkill'` — see that option.
+ *
+ * **Activation lifetime: the rest of the turn.** Once the model picks a
+ * skill with `read_skill`, the activation lasts until the turn ends — every
+ * later iteration of that `run()` keeps the body active, and there is no
+ * mid-turn deactivation (nothing removes an id from
+ * `ctx.activatedInjectionIds`; the next `run()` starts clean). This is
+ * deliberate: the cache layer's skill history and the context ledger both
+ * lean on the cumulative property. A skill that should stop applying
+ * mid-turn is a `rule` trigger or a `skillGraph()` route, not a read_skill
+ * pick.
+ *
+ * Produces an `Injection` with:
+ *   - flavor: `'skill'`
+ *   - trigger: `{ kind: 'llm-activated', viaToolName: 'read_skill' }`
+ *   - inject: `{ systemPrompt: body, tools }`
+ *
+ * The Agent integration auto-attaches the `read_skill` tool when one
+ * or more Skills are present. When the LLM calls
+ * `read_skill('billing')`, the engine adds `'billing'` to
+ * `ctx.activatedInjectionIds`; the next iteration's evaluator
+ * matches this Skill's `id`, activates it, and the body lands in the
+ * slot subflows (plus the tools, for an `autoActivate` Skill — every
+ * other Skill's tools were already there).
+ *
+ * @example
+ *   const billingSkill = defineSkill({
+ *     id: 'billing',
+ *     description: 'Use for refunds, charges, billing questions.',
+ *     body: 'When handling billing: confirm identity first, then…',
+ *     tools: [refundTool, chargeHistoryTool],
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineSkillInjection = exports.defineSkill = exports.resolveSurfaceMode = void 0;
+const plainLine_js_1 = require("../../lib/plainLine.js");
+const optionKeys_js_1 = require("../optionKeys.js");
+const applyCachePolicy_js_1 = require("../../cache/applyCachePolicy.js");
+const skillSteps_js_1 = require("../skillSteps.js");
+const skillVocabulary_js_1 = require("../skillVocabulary.js");
+/**
+ * Resolve `surfaceMode: 'auto'` to a concrete mode based on provider
+ * + model. The defaults match the per-provider attention profile
+ * documented in the Skills, explained essay:
+ *
+ *   - Claude >= 3.5  → 'both'      (cheap to cache, high adherence)
+ *   - Claude pre-3.5 → 'tool-only' (recency-first more reliable)
+ *   - OpenAI / Bedrock / Ollama / Mock / unknown → 'tool-only'
+ *
+ * Pure function — no side effects. Consumers can call directly to
+ * inspect what `'auto'` will resolve to in their stack.
+ */
+function resolveSurfaceMode(provider, model) {
+    const p = provider.toLowerCase();
+    if (p === 'anthropic') {
+        // Match both naming styles in current use:
+        //   - claude-3-5-sonnet-..., claude-3.5-...
+        //   - claude-sonnet-4-..., claude-haiku-4-..., claude-opus-4-..., claude-4-...
+        // Anything matching "Claude >= 3.5" gets 'both'; older Claudes get 'tool-only'.
+        if (model && /(claude-3-5|claude-3\.5|claude-(?:opus-|sonnet-|haiku-)?[4-9])/i.test(model)) {
+            return 'both';
+        }
+        return 'tool-only';
+    }
+    return 'tool-only';
+}
+exports.resolveSurfaceMode = resolveSurfaceMode;
+const SKILL_OPTION_KEYS = {
+    id: true,
+    description: true,
+    title: true,
+    body: true,
+    tools: true,
+    surfaceMode: true,
+    autoActivate: true,
+    steps: true,
+    onSkip: true,
+    produces: true,
+    consumes: true,
+    provider: true,
+    model: true,
+    cache: true,
+};
+/** The unified facade consumes `type`; all skill options keep one owner. */
+const SKILL_INJECTION_OPTION_KEYS = { ...SKILL_OPTION_KEYS, type: true };
+/** The longest skill title a report prints. */
+const MAX_SKILL_TITLE_CHARS = 60;
+/**
+ * Validate a declared `title` — refused where the author wrote it. `undefined`
+ * when none was declared; otherwise the trimmed title.
+ */
+function readSkillTitle(id, raw) {
+    if (raw === undefined)
+        return undefined;
+    const at = `defineSkill(${id}): \`title\``;
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        throw new Error(`${at} must be a non-empty string — or omit it; a report then prints the id.`);
+    }
+    const title = raw.trim();
+    const notPlain = (0, plainLine_js_1.plainLineProblem)(at, title);
+    if (notPlain !== undefined)
+        throw new Error(notPlain);
+    if (title.length > MAX_SKILL_TITLE_CHARS) {
+        throw new Error(`${at} is ${title.length} characters; the limit is ${MAX_SKILL_TITLE_CHARS}.`);
+    }
+    if (title === id) {
+        throw new Error(`${at} is the id itself — a title is the plain name a person reads; omit it.`);
+    }
+    return title;
+}
+function defineSkill(opts) {
+    return createSkill(opts, SKILL_OPTION_KEYS);
+}
+exports.defineSkill = defineSkill;
+/**
+ * Internal facade entry, deliberately absent from every public barrel.
+ * Validate the original declaration, preserving inherited options and getter
+ * receivers. Only this entry consumes the unified factory's discriminant.
+ */
+function defineSkillInjection(opts) {
+    return createSkill(opts, SKILL_INJECTION_OPTION_KEYS);
+}
+exports.defineSkillInjection = defineSkillInjection;
+/** One validation/construction path for named and discriminated declarations. */
+function createSkill(opts, optionKeys) {
+    if (!opts.id || opts.id.trim().length === 0) {
+        throw new Error('defineSkill: `id` is required and must be non-empty.');
+    }
+    if (!opts.description || opts.description.length === 0) {
+        throw new Error(`defineSkill(${opts.id}): \`description\` is required (LLM uses it to decide when to activate).`);
+    }
+    if (!opts.body || opts.body.length === 0) {
+        throw new Error(`defineSkill(${opts.id}): \`body\` is required.`);
+    }
+    (0, optionKeys_js_1.assertKnownOptions)(`defineSkill(${opts.id})`, opts, optionKeys);
+    const title = readSkillTitle(opts.id, opts.title);
+    // Steps checkup (9.18.0) — all the data is in hand HERE, so every step
+    // refusal happens here: unknown tool, empty note/tool, steps:[], steps
+    // without tools, onSkip without steps. See skillSteps.ts, the grammar owner.
+    (0, skillSteps_js_1.validateSkillSteps)(opts.id, {
+        ...(opts.steps !== undefined && { steps: opts.steps }),
+        ...(opts.onSkip !== undefined && { onSkip: opts.onSkip }),
+        toolNames: new Set((opts.tools ?? []).map((t) => t.schema.name)),
+    });
+    // The artifact vocabularies (9.25.0) — same law, same authoring point: a
+    // blank kind, an empty list or a repeat is refused HERE, where the
+    // declaration is written. Whether a consumed kind is SATISFIABLE needs the
+    // whole agent and is checked at build (`skillVocabulary.ts`).
+    (0, skillVocabulary_js_1.assertArtifactVocabulary)(`defineSkill(${opts.id})`, 'produces', opts.produces);
+    (0, skillVocabulary_js_1.assertArtifactVocabulary)(`defineSkill(${opts.id})`, 'consumes', opts.consumes);
+    return Object.freeze({
+        id: opts.id,
+        description: opts.description,
+        // Top-level, not a `metadata` key: at least one path rebuilds `metadata`
+        // wholesale (`toolsFromActiveSkill`), and a top-level field survives every
+        // `{ ...injection }` spread (the `templated` precedent).
+        ...(title !== undefined && { title }),
+        flavor: 'skill',
+        trigger: {
+            kind: 'llm-activated',
+            viaToolName: 'read_skill',
+        },
+        inject: {
+            systemPrompt: opts.body,
+            ...(opts.tools && opts.tools.length > 0 && { tools: opts.tools }),
+        },
+        // Skill-specific options live in metadata. The engine reads them
+        // when present; absent metadata = current behavior. `surfaceMode` and
+        // `autoActivate` are read at runtime.
+        //
+        // `cache` also rides this bag when a caller sets it.
+        metadata: Object.freeze({
+            surfaceMode: opts.surfaceMode ?? 'auto',
+            ...(opts.autoActivate && { autoActivate: opts.autoActivate }),
+            // The skill's brain (9.19.0) — rides the metadata bag like every other
+            // per-skill option. NEVER projected (`projectActiveInjection`'s
+            // allow-list does not carry it), so the live provider object stays on
+            // the closure-held list and never crosses a scope boundary.
+            // `Agent.build()` folds + validates it (`skillBrains.ts`).
+            ...(opts.provider !== undefined && { provider: opts.provider }),
+            ...(opts.model !== undefined && { model: opts.model }),
+            // The procedure, as data (9.18.0). `Agent` folds these into one frozen
+            // StepPlan map at build; the engine ignores them everywhere else, so a
+            // consumer reading skills off this bag sees exactly what was declared.
+            ...(opts.steps &&
+                opts.steps.length > 0 && {
+                steps: Object.freeze(opts.steps.map((s) => Object.freeze({ ...s }))),
+                onSkip: opts.onSkip ?? 'advance',
+            }),
+            // The artifact vocabularies (9.25.0) — recorded as declared, on the same
+            // bag every other per-skill option rides. Build-time checks read them
+            // from here, and so will a lens; the engine never does. Absent when not
+            // declared, so a skill without them serializes byte-identically.
+            ...(opts.produces !== undefined && { produces: Object.freeze([...opts.produces]) }),
+            ...(opts.consumes !== undefined && { consumes: Object.freeze([...opts.consumes]) }),
+            cache: (0, applyCachePolicy_js_1.resolveCachePolicy)('skill', opts.cache),
+        }),
+    });
+}
+//# sourceMappingURL=defineSkill.js.map

package/dist/injection-engine/factories/defineSkill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineSkill.js","sourceRoot":"","sources":["../../../src/injection-engine/factories/defineSkill.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;;;AAEH,yDAA0D;AAC1D,oDAAsD;AAGtD,yEAAqE;AAErE,oDAAyF;AACzF,8DAAiE;AAsMjE;;;;;;;;;;;GAWG;AACH,SAAgB,kBAAkB,CAAC,QAAgB,EAAE,KAAc;IACjE,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,CAAC,KAAK,WAAW,EAAE,CAAC;QACtB,2CAA2C;QAC3C,4CAA4C;QAC5C,+EAA+E;QAC/E,gFAAgF;QAChF,IAAI,KAAK,IAAI,iEAAiE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3F,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAbD,gDAaC;AAED,MAAM,iBAAiB,GAAG;IACxB,EAAE,EAAE,IAAI;IACR,WAAW,EAAE,IAAI;IACjB,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,WAAW,EAAE,IAAI;IACjB,YAAY,EAAE,IAAI;IAClB,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,IAAI;IACZ,QAAQ,EAAE,IAAI;IACd,QAAQ,EAAE,IAAI;IACd,QAAQ,EAAE,IAAI;IACd,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,IAAI;CACqC,CAAC;AAEnD,4EAA4E;AAC5E,MAAM,2BAA2B,GAAG,EAAE,GAAG,iBAAiB,EAAE,IAAI,EAAE,IAAI,EAGrE,CAAC;AAEF,+CAA+C;AAC/C,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;GAGG;AACH,SAAS,cAAc,CAAC,EAAU,EAAE,GAAY;IAC9C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,EAAE,GAAG,eAAe,EAAE,cAAc,CAAC;IAC3C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,wEAAwE,CAAC,CAAC;IACjG,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACzB,MAAM,QAAQ,GAAG,IAAA,+BAAgB,EAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC7C,IAAI,QAAQ,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtD,IAAI,KAAK,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,MAAM,6BAA6B,qBAAqB,GAAG,CAAC,CAAC;IACjG,CAAC;IACD,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,wEAAwE,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,WAAW,CAAC,IAAwB;IAClD,OAAO,WAAW,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;AAC9C,CAAC;AAFD,kCAEC;AAED;;;;GAIG;AACH,SAAgB,oBAAoB,CAClC,IAAqD;IAErD,OAAO,WAAW,CAAC,IAAI,EAAE,2BAA2B,CAAC,CAAC;AACxD,CAAC;AAJD,oDAIC;AAED,iFAAiF;AACjF,SAAS,WAAW,CAClB,IAAwB,EACxB,UAA0C;IAE1C,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,CAAC,EAAE,0EAA0E,CACjG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,CAAC,EAAE,0BAA0B,CAAC,CAAC;IACpE,CAAC;IACD,IAAA,kCAAkB,EAAC,eAAe,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAChE,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,uEAAuE;IACvE,uEAAuE;IACvE,6EAA6E;IAC7E,IAAA,kCAAkB,EAAC,IAAI,CAAC,EAAE,EAAE;QAC1B,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACtD,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QACzD,SAAS,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;KACjE,CAAC,CAAC;IACH,yEAAyE;IACzE,mEAAmE;IACnE,2EAA2E;IAC3E,8DAA8D;IAC9D,IAAA,6CAAwB,EAAC,eAAe,IAAI,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/E,IAAA,6CAAwB,EAAC,eAAe,IAAI,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/E,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,yEAAyE;QACzE,2EAA2E;QAC3E,yDAAyD;QACzD,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;QACrC,MAAM,EAAE,OAAgB;QACxB,OAAO,EAAE;YACP,IAAI,EAAE,eAAwB;YAC9B,WAAW,EAAE,YAAY;SAC1B;QACD,MAAM,EAAE;YACN,YAAY,EAAE,IAAI,CAAC,IAAI;YACvB,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;SAClE;QACD,iEAAiE;QACjE,sEAAsE;QACtE,sCAAsC;QACtC,EAAE;QACF,qDAAqD;QACrD,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;YACtB,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,MAAM;YACvC,GAAG,CAAC,IAAI,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;YAC7D,uEAAuE;YACvE,gEAAgE;YAChE,sEAAsE;YACtE,4DAA4D;YAC5D,2DAA2D;YAC3D,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC/D,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YACtD,uEAAuE;YACvE,uEAAuE;YACvE,uEAAuE;YACvE,GAAG,CAAC,IAAI,CAAC,KAAK;gBACZ,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI;gBACvB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;gBACpE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAK,SAAmB;aAC5C,CAAC;YACJ,yEAAyE;YACzE,sEAAsE;YACtE,wEAAwE;YACxE,iEAAiE;YACjE,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YACnF,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YACnF,KAAK,EAAE,IAAA,wCAAkB,EAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;SAC/C,CAAC;KACH,CAAyB,CAAC;AAC7B,CAAC"}

package/dist/injection-engine/factories/defineSteering.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * defineSteering — sugar for always-on system-prompt Injections.
+ *
+ * Steering docs are the simplest form of context engineering: a fixed
+ * piece of guidance the LLM should follow on every iteration. Style
+ * guides, output format rules, persona statements, safety policies.
+ *
+ * Produces an `Injection` with:
+ *   - flavor: `'steering'`
+ *   - trigger: `{ kind: 'always' }`
+ *   - inject: `{ systemPrompt: prompt }`
+ *
+ * @example
+ *   const jsonOnly = defineSteering({
+ *     id: 'json-only',
+ *     description: 'Always respond with valid JSON.',
+ *     prompt: 'Respond with JSON only. No prose. No markdown.',
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineSteering = void 0;
+const applyCachePolicy_js_1 = require("../../cache/applyCachePolicy.js");
+function defineSteering(opts) {
+    if (!opts.id || opts.id.trim().length === 0) {
+        throw new Error('defineSteering: `id` is required and must be non-empty.');
+    }
+    if (!opts.prompt || opts.prompt.length === 0) {
+        throw new Error(`defineSteering(${opts.id}): \`prompt\` is required.`);
+    }
+    const cache = (0, applyCachePolicy_js_1.resolveCachePolicy)('steering', opts.cache);
+    return Object.freeze({
+        id: opts.id,
+        ...(opts.description && { description: opts.description }),
+        flavor: 'steering',
+        trigger: { kind: 'always' },
+        inject: { systemPrompt: opts.prompt },
+        metadata: Object.freeze({ cache }),
+    });
+}
+exports.defineSteering = defineSteering;
+//# sourceMappingURL=defineSteering.js.map

package/dist/injection-engine/factories/defineSteering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineSteering.js","sourceRoot":"","sources":["../../../src/injection-engine/factories/defineSteering.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAGH,yEAAqE;AAqBrE,SAAgB,cAAc,CAAC,IAA2B;IACxD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAC,EAAE,4BAA4B,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,KAAK,GAAG,IAAA,wCAAkB,EAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1D,MAAM,EAAE,UAAmB;QAC3B,OAAO,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE;QACpC,MAAM,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,MAAM,EAAE;QACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;KACnC,CAAyB,CAAC;AAC7B,CAAC;AAhBD,wCAgBC"}

package/dist/injection-engine/factories/defineStepsHint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineStepsHint.js","sourceRoot":"","sources":["../../../src/injection-engine/factories/defineStepsHint.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAaH;;;;;;GAMG;AACU,QAAA,uBAAuB,GAAG,gBAAyB,CAAC;AAEjE,MAAM,YAAY,GAChB,oFAAoF;IACpF,oFAAoF;IACpF,wFAAwF;IACxF,gEAAgE,CAAC;AAEnE,SAAgB,eAAe,CAAC,UAA4B,EAAE;IAC5D,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,kBAAkB;QACpC,MAAM,EAAE,cAAc;QACtB,WAAW,EAAE,+DAA+D;QAC5E,OAAO,EAAE;YACP,IAAI,EAAE,MAAM;YACZ,uEAAuE;YACvE,sEAAsE;YACtE,qEAAqE;YACrE,kEAAkE;YAClE,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAClB,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW,CAAC,KAAK;SACjF;QACD,QAAQ,EAAE,EAAE,CAAC,+BAAuB,CAAC,EAAE,IAAI,EAAE;QAC7C,MAAM,EAAE,EAAE,YAAY,EAAE,OAAO,CAAC,IAAI,IAAI,YAAY,EAAE;KACvD,CAAC;AACJ,CAAC;AAjBD,0CAiBC"}

package/dist/injection-engine/hostContract.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * hostContract — THE BOUNDARY between the skill-graph runtime and whatever
+ * runs it (9.34.0).
+ *
+ * The skill graph is a pure decision layer: given an `InjectionContext` it
+ * says which skill the cursor is in, which skills are reachable from there,
+ * and which injections are active. It does not call a model, does not own a
+ * loop, and does not know what a `Tool` is in any particular framework. This
+ * module is the small set of shapes that statement needs to be TRUE:
+ *
+ *   • {@link SkillToolSchema} / {@link SkillTool} — the narrow shape a skill's
+ *     tools must have for the graph to reason about them (a name, a
+ *     description, an input schema, something to run). agentfootprint's own
+ *     `Tool` structurally satisfies it; so would any other framework's.
+ *   • {@link SkillToolDescriptor} — a PLAIN description of a tool the graph
+ *     needs to exist (`read_skill` above all, which is how the model moves
+ *     the cursor). The graph describes it; the host constructs it in its own
+ *     tool type.
+ *   • {@link SkillCachePolicy} — the cache directive that rides the
+ *     `ActiveInjection` projection across the host boundary.
+ *   • {@link SkillGraphHost} — the obligations a host must meet for the graph
+ *     to route correctly. Documentation as a type.
+ *
+ * WHY STRUCTURAL COPIES. `SkillToolSchema` and `SkillCachePolicy` are
+ * field-for-field mirrors of `provider-contract/types.ts#LLMToolSchema` and
+ * `cache/types.ts#CachePolicy`. Mirroring them is what lets a foreign host
+ * satisfy the boundary without importing an adapter layer it does not use;
+ * TypeScript's structural typing then makes the two spellings mutually
+ * assignable, so nothing inside agentfootprint changed shape. The mirrors are
+ * PINNED against their originals by
+ * `test/injection-engine/skill-graph-fence.test.ts`, which fails on drift
+ * in either direction.
+ *
+ * Zone: PURE CORE. Zero imports, by construction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=hostContract.js.map

package/dist/injection-engine/hostContract.js.map

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

package/dist/injection-engine/index.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * agentfootprint Injection Engine — public barrel.
+ *
+ * The unifying primitive of agentfootprint context engineering.
+ * One `Injection` type. One `InjectionEngine` subflow. N typed sugar
+ * factories. See `README.md` in this folder for the full concept.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constrainedEnumPick = exports.llmClassifier = exports.validateIntentScores = exports.CLASSIFIER_SCORER_UNAVAILABLE = exports.CLASSIFIER_SCORER_QUESTION = exports.classifierScorer = exports.rankEntries = exports.embeddingScorer = exports.keywordScorer = exports.classifySkillTarget = exports.SKILL_GRAPH_DEFERRED_CONTRACT_KEY = exports.plainGuardCaption = exports.GUARD_HOP_KEYS = exports.SKILL_GRAPH_METADATA_KEY = exports.formatCheckup = exports.decideSkill = exports.defineSkillMap = exports.skillGraph = exports.defineInjection = exports.defineFact = exports.defineSteering = exports.useSkillGraphDevMode = exports.TOOL_RESULT_STATUSES = exports.readSkillDescriptor = exports.listSkillsDescriptor = exports.buildSkipStepTool = exports.buildReadSkillTool = exports.buildListSkillsTool = exports.runbookFromDir = exports.skillsFromDir = exports.SkillRegistry = exports.vocabularyOf = exports.checkArtifactVocabularies = exports.STEPS_HINT_METADATA_KEY = exports.defineStepsHint = exports.skipStepDescriptor = exports.SKIP_STEP_TOOL_NAME = exports.pointerOf = exports.resolveSurfaceMode = exports.defineSkill = exports.MENU_HINT_METADATA_KEY = exports.defineMenuHint = exports.READS_ENTRY_SCORES_METADATA_KEY = exports.defineRelevanceHint = exports.defineInstruction = exports.buildInjectionEngineSubflow = exports.evaluateInjections = exports.saidByPerson = exports.toolResultsOf = exports.projectActiveInjection = void 0;
+exports.skillToolNames = exports.checkSkillContracts = exports.checkSkillContract = exports.menuOutstanding = exports.decideTier2 = exports.DEFAULT_ROUTING_POLICY = exports.MENU_SIZE = exports.NEAR_TIE_MARGIN = void 0;
+// Bind the pure core's dev-warn seam to footprintjs's `isDevMode` (9.34.0).
+// Side-effect import, on purpose: the skill-graph core no longer imports the
+// engine, so SOMEONE has to hand it the dev flag, and this barrel is on every
+// path inside this package that can reach `skillGraph()`. Without it,
+// `enableDevMode()` would stop switching skill-graph warnings on — the one
+// behavior the fence refactor must not change. `agentfootprint/skill-graph`
+// deliberately skips it; see `devWarn.ts`.
+require("./devWarnHost.js");
+// POJO projection — used by slot subflows + advanced consumers
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "projectActiveInjection", { enumerable: true, get: function () { return types_js_1.projectActiveInjection; } });
+// The iteration's tool-result batch with the singular fallback applied
+// (9.16.0) — the one reader `rule` predicates should use to see every call of
+// a parallel batch, not only the last (`ctx.toolResults ?? [ctx.lastToolResult]`).
+var types_js_2 = require("./types.js");
+Object.defineProperty(exports, "toolResultsOf", { enumerable: true, get: function () { return types_js_2.toolResultsOf; } });
+// The messages a PERSON wrote (9.84.0) — the one reader for a predicate that
+// judges what was said. `ctx.history` also holds the five user-role messages
+// this library writes itself (compaction frame, drop notice, schema-check
+// correction, evidence-check correction, delivered message), and a rule
+// scanning it raw matches our own bookkeeping.
+var types_js_3 = require("./types.js");
+Object.defineProperty(exports, "saidByPerson", { enumerable: true, get: function () { return types_js_3.saidByPerson; } });
+// Engine
+var evaluator_js_1 = require("./evaluator.js");
+Object.defineProperty(exports, "evaluateInjections", { enumerable: true, get: function () { return evaluator_js_1.evaluateInjections; } });
+var buildInjectionEngineSubflow_js_1 = require("./buildInjectionEngineSubflow.js");
+Object.defineProperty(exports, "buildInjectionEngineSubflow", { enumerable: true, get: function () { return buildInjectionEngineSubflow_js_1.buildInjectionEngineSubflow; } });
+// Sugar factories — Ships four; more flavors planned (RAG / Memory / Guardrail)
+var defineInstruction_js_1 = require("./factories/defineInstruction.js");
+Object.defineProperty(exports, "defineInstruction", { enumerable: true, get: function () { return defineInstruction_js_1.defineInstruction; } });
+var defineRelevanceHint_js_1 = require("./factories/defineRelevanceHint.js");
+Object.defineProperty(exports, "defineRelevanceHint", { enumerable: true, get: function () { return defineRelevanceHint_js_1.defineRelevanceHint; } });
+Object.defineProperty(exports, "READS_ENTRY_SCORES_METADATA_KEY", { enumerable: true, get: function () { return defineRelevanceHint_js_1.READS_ENTRY_SCORES_METADATA_KEY; } });
+var defineMenuHint_js_1 = require("./factories/defineMenuHint.js");
+Object.defineProperty(exports, "defineMenuHint", { enumerable: true, get: function () { return defineMenuHint_js_1.defineMenuHint; } });
+Object.defineProperty(exports, "MENU_HINT_METADATA_KEY", { enumerable: true, get: function () { return defineMenuHint_js_1.MENU_HINT_METADATA_KEY; } });
+var defineSkill_js_1 = require("./factories/defineSkill.js");
+Object.defineProperty(exports, "defineSkill", { enumerable: true, get: function () { return defineSkill_js_1.defineSkill; } });
+Object.defineProperty(exports, "resolveSurfaceMode", { enumerable: true, get: function () { return defineSkill_js_1.resolveSurfaceMode; } });
+// Steps-as-data (9.18.0) — the procedure grammar. `skillSteps.ts` is the ONE
+// owner of the types, the pointer's shape and every sentence the model reads;
+// the public slice here is what a consumer needs to DECLARE steps, READ the
+// pointer off a snapshot (`pointerOf(sharedState.stepPointer)`), and compose
+// the integrity tool into custom wiring (the buildReadSkillTool precedent).
+var skillSteps_js_1 = require("./skillSteps.js");
+Object.defineProperty(exports, "pointerOf", { enumerable: true, get: function () { return skillSteps_js_1.pointerOf; } });
+Object.defineProperty(exports, "SKIP_STEP_TOOL_NAME", { enumerable: true, get: function () { return skillSteps_js_1.SKIP_STEP_TOOL_NAME; } });
+Object.defineProperty(exports, "skipStepDescriptor", { enumerable: true, get: function () { return skillSteps_js_1.skipStepDescriptor; } });
+var defineStepsHint_js_1 = require("./factories/defineStepsHint.js");
+Object.defineProperty(exports, "defineStepsHint", { enumerable: true, get: function () { return defineStepsHint_js_1.defineStepsHint; } });
+Object.defineProperty(exports, "STEPS_HINT_METADATA_KEY", { enumerable: true, get: function () { return defineStepsHint_js_1.STEPS_HINT_METADATA_KEY; } });
+// Artifact vocabularies (9.25.0) — `produces`/`consumes` on a skill or a step.
+// The public slice is what a consumer needs to READ a skill's declared data
+// legs off its metadata (`vocabularyOf`, for a lens or an inventory) and to run
+// the satisfiability check itself over a list of skills the library did not
+// assemble. `assertArtifactVocabulary` stays private: it is the authoring-time
+// refusal `defineSkill` already applies.
+var skillVocabulary_js_1 = require("./skillVocabulary.js");
+Object.defineProperty(exports, "checkArtifactVocabularies", { enumerable: true, get: function () { return skillVocabulary_js_1.checkArtifactVocabularies; } });
+Object.defineProperty(exports, "vocabularyOf", { enumerable: true, get: function () { return skillVocabulary_js_1.vocabularyOf; } });
+var SkillRegistry_js_1 = require("./SkillRegistry.js");
+Object.defineProperty(exports, "SkillRegistry", { enumerable: true, get: function () { return SkillRegistry_js_1.SkillRegistry; } });
+// File-authored skills — a loader over `defineSkill`, not a second mechanism.
+// Node-only (reads the filesystem); node:fs is imported lazily inside the call
+// so this barrel stays safe to import from a browser bundle.
+// `runbookFromDir` is the same loader read as a whole runbook — skills PLUS the
+// edges each file's `routes:` declares, ready for `skillGraph({ ...runbook })`.
+var skillsFromDir_js_1 = require("./skillsFromDir.js");
+Object.defineProperty(exports, "skillsFromDir", { enumerable: true, get: function () { return skillsFromDir_js_1.skillsFromDir; } });
+Object.defineProperty(exports, "runbookFromDir", { enumerable: true, get: function () { return skillsFromDir_js_1.runbookFromDir; } });
+// Skill-tool builders — used by SkillRegistry.toTools() and the Agent's
+// auto-attach path. Exported so consumers building custom tool wiring
+// (e.g., gatedTools chains) can compose the same `list_skills` /
+// `read_skill` tools directly.
+var skillTools_js_1 = require("./skillTools.js");
+Object.defineProperty(exports, "buildListSkillsTool", { enumerable: true, get: function () { return skillTools_js_1.buildListSkillsTool; } });
+Object.defineProperty(exports, "buildReadSkillTool", { enumerable: true, get: function () { return skillTools_js_1.buildReadSkillTool; } });
+Object.defineProperty(exports, "buildSkipStepTool", { enumerable: true, get: function () { return skillTools_js_1.buildSkipStepTool; } });
+// The graph's own DESCRIPTIONS of the tools it needs (9.34.0) — the POJOs the
+// builders above wrap. Exported because a host composing its own tool objects
+// (another framework, a custom ToolProvider) should read `read_skill`'s enum,
+// reachability offer and result sentences from the library rather than
+// re-writing them. Also the whole surface of `agentfootprint/skill-graph`.
+var skillToolDescriptors_js_1 = require("./skillToolDescriptors.js");
+Object.defineProperty(exports, "listSkillsDescriptor", { enumerable: true, get: function () { return skillToolDescriptors_js_1.listSkillsDescriptor; } });
+Object.defineProperty(exports, "readSkillDescriptor", { enumerable: true, get: function () { return skillToolDescriptors_js_1.readSkillDescriptor; } });
+var toolOutcome_js_1 = require("../semantics/toolOutcome.js");
+Object.defineProperty(exports, "TOOL_RESULT_STATUSES", { enumerable: true, get: function () { return toolOutcome_js_1.TOOL_RESULT_STATUSES; } });
+var devWarn_js_1 = require("./devWarn.js");
+Object.defineProperty(exports, "useSkillGraphDevMode", { enumerable: true, get: function () { return devWarn_js_1.useSkillGraphDevMode; } });
+var defineSteering_js_1 = require("./factories/defineSteering.js");
+Object.defineProperty(exports, "defineSteering", { enumerable: true, get: function () { return defineSteering_js_1.defineSteering; } });
+var defineFact_js_1 = require("./factories/defineFact.js");
+Object.defineProperty(exports, "defineFact", { enumerable: true, get: function () { return defineFact_js_1.defineFact; } });
+// Unified factory — a `type` discriminant routes to the four named factories
+// above. Use when the flavor is chosen programmatically; prefer the named
+// factories when you know the flavor at author time.
+var defineInjection_js_1 = require("./factories/defineInjection.js");
+Object.defineProperty(exports, "defineInjection", { enumerable: true, get: function () { return defineInjection_js_1.defineInjection; } });
+// Declarative skill graph (proposal 002) — declare skills + routing edges →
+// graph-derived triggers + a drawable topology. Sugar over the trigger model.
+var skillGraph_js_1 = require("./skillGraph.js");
+Object.defineProperty(exports, "skillGraph", { enumerable: true, get: function () { return skillGraph_js_1.skillGraph; } });
+// The official vocabulary (9.51.0): you declare the SkillMap; the agent is
+// the SkillWalker; the recording carries both. `defineSkillMap` is a
+// permanent reference-equal alias of `skillGraph`, `SkillMap` of
+// `SkillGraph` — both names ship forever, neither is a rename.
+Object.defineProperty(exports, "defineSkillMap", { enumerable: true, get: function () { return skillGraph_js_1.defineSkillMap; } });
+Object.defineProperty(exports, "decideSkill", { enumerable: true, get: function () { return skillGraph_js_1.decideSkill; } });
+// 8.7.0 — render a `graph.checkup()` for a log line or a CI failure. The formatter
+// the library itself uses; without it every consumer wrote their own. `checkupGraph`
+// stays private: its input is the graph's internal wiring shape, and `graph.checkup()`
+// is already the door to it.
+Object.defineProperty(exports, "formatCheckup", { enumerable: true, get: function () { return skillGraph_js_1.formatCheckup; } });
+Object.defineProperty(exports, "SKILL_GRAPH_METADATA_KEY", { enumerable: true, get: function () { return skillGraph_js_1.SKILL_GRAPH_METADATA_KEY; } });
+// Guards-as-data on route edges (9.51.0) — the SkillWalker's guard mover as
+// data: `guard:` beside the code `when`, compiled once into the predicate,
+// the serializable `SkillGuardData` (edges/provenance/`skill.graph_declared`)
+// and the per-condition evidence (`cursorMove.guard`/`guardsClosed`).
+Object.defineProperty(exports, "GUARD_HOP_KEYS", { enumerable: true, get: function () { return skillGraph_js_1.GUARD_HOP_KEYS; } });
+Object.defineProperty(exports, "plainGuardCaption", { enumerable: true, get: function () { return skillGraph_js_1.plainGuardCaption; } });
+// The graph's note that its body-contract checks wait for Agent build (present
+// only when built without `knownTools`) — see SkillGraph.deferredBodyContract.
+// The note rides the graph AND each compiled skill's metadata (under
+// SKILL_GRAPH_DEFERRED_CONTRACT_KEY), so Agent build honors it whichever way
+// the skills arrive — `.skillGraph(graph)` or `.skills({ list: () => graph.skills })`.
+Object.defineProperty(exports, "SKILL_GRAPH_DEFERRED_CONTRACT_KEY", { enumerable: true, get: function () { return skillGraph_js_1.SKILL_GRAPH_DEFERRED_CONTRACT_KEY; } });
+// The ONE owner of "is this target the cursor?" (9.86.0) — every gate,
+// description and refusal switches on it instead of re-deriving it.
+Object.defineProperty(exports, "classifySkillTarget", { enumerable: true, get: function () { return skillGraph_js_1.classifySkillTarget; } });
+var entryScorer_js_1 = require("./entryScorer.js");
+Object.defineProperty(exports, "keywordScorer", { enumerable: true, get: function () { return entryScorer_js_1.keywordScorer; } });
+Object.defineProperty(exports, "embeddingScorer", { enumerable: true, get: function () { return entryScorer_js_1.embeddingScorer; } });
+Object.defineProperty(exports, "rankEntries", { enumerable: true, get: function () { return entryScorer_js_1.rankEntries; } });
+var classifierScorer_js_1 = require("./classifierScorer.js");
+Object.defineProperty(exports, "classifierScorer", { enumerable: true, get: function () { return classifierScorer_js_1.classifierScorer; } });
+Object.defineProperty(exports, "CLASSIFIER_SCORER_QUESTION", { enumerable: true, get: function () { return classifierScorer_js_1.CLASSIFIER_SCORER_QUESTION; } });
+Object.defineProperty(exports, "CLASSIFIER_SCORER_UNAVAILABLE", { enumerable: true, get: function () { return classifierScorer_js_1.CLASSIFIER_SCORER_UNAVAILABLE; } });
+// The turn-start routing cascade (SG-C, 9.17.0) — the intent-scorer port +
+// the built-in LLM classifier, the tie policy that judges tier 2, and the
+// graph surfaces the agent consumes. keywordScorer/embeddingScorer above ARE
+// IntentScorers too (same factories, a second arity).
+var intentScorer_js_1 = require("./intentScorer.js");
+Object.defineProperty(exports, "validateIntentScores", { enumerable: true, get: function () { return intentScorer_js_1.validateIntentScores; } });
+var llmClassifier_js_1 = require("./llmClassifier.js");
+Object.defineProperty(exports, "llmClassifier", { enumerable: true, get: function () { return llmClassifier_js_1.llmClassifier; } });
+// The constrained-enum machinery behind the classifier AND the tier-3
+// decider (9.19.0) — one model call that can only answer from a fixed list.
+var constrainedEnumPick_js_1 = require("./constrainedEnumPick.js");
+Object.defineProperty(exports, "constrainedEnumPick", { enumerable: true, get: function () { return constrainedEnumPick_js_1.constrainedEnumPick; } });
+var routingPolicy_js_1 = require("./routingPolicy.js");
+Object.defineProperty(exports, "NEAR_TIE_MARGIN", { enumerable: true, get: function () { return routingPolicy_js_1.NEAR_TIE_MARGIN; } });
+Object.defineProperty(exports, "MENU_SIZE", { enumerable: true, get: function () { return routingPolicy_js_1.MENU_SIZE; } });
+Object.defineProperty(exports, "DEFAULT_ROUTING_POLICY", { enumerable: true, get: function () { return routingPolicy_js_1.DEFAULT_ROUTING_POLICY; } });
+Object.defineProperty(exports, "decideTier2", { enumerable: true, get: function () { return routingPolicy_js_1.decideTier2; } });
+Object.defineProperty(exports, "menuOutstanding", { enumerable: true, get: function () { return routingPolicy_js_1.menuOutstanding; } });
+var skillContract_js_1 = require("./skillContract.js");
+Object.defineProperty(exports, "checkSkillContract", { enumerable: true, get: function () { return skillContract_js_1.checkSkillContract; } });
+Object.defineProperty(exports, "checkSkillContracts", { enumerable: true, get: function () { return skillContract_js_1.checkSkillContracts; } });
+Object.defineProperty(exports, "skillToolNames", { enumerable: true, get: function () { return skillContract_js_1.skillToolNames; } });
+//# sourceMappingURL=index.js.map

package/dist/injection-engine/index.js.map

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