agentfootprint 6.44.0 → 6.45.0

package/dist/esm/lib/injection-engine/SkillRegistry.d.ts

@@ -0,0 +1,147 @@
+/**
+ * SkillRegistry — centralized governance for Skills across one or
+ * more Agents.
+ *
+ * Most apps register Skills directly on the Agent via `.skill(s)`.
+ * Once you have multiple Agents that share a common skill catalog
+ * (a customer-support pool, a research team, a multi-step workflow
+ * where each step uses different overlapping skills), hand-syncing
+ * `.skill()` calls per Agent gets fragile.
+ *
+ * `SkillRegistry` is the answer: register once, attach to many
+ * Agents via `.skills(registry)`. Add a Skill to the registry and
+ * every consumer Agent picks it up at next build.
+ *
+ * @example
+ *   const registry = new SkillRegistry();
+ *   registry.register(billingSkill);
+ *   registry.register(refundSkill);
+ *
+ *   const supportAgent = Agent.create({ provider }).skills(registry).build();
+ *   const escalationAgent = Agent.create({ provider }).skills(registry).build();
+ *
+ *   // Add a new skill — both agents pick it up at next build.
+ *   registry.register(complianceSkill);
+ */
+import type { Injection } from './types.js';
+import { type SkillToolPair } from './skillTools.js';
+import { type SurfaceMode } from './factories/defineSkill.js';
+/**
+ * Options for `new SkillRegistry({...})`. All fields are optional;
+ * the empty-object form (`new SkillRegistry()`) is the v2.4 surface.
+ *
+ * @see SkillRegistry.resolveForSkill — applies the cascade
+ */
+export interface SkillRegistryOptions {
+    /**
+     * Registry-level default `surfaceMode`. Applies to skills whose own
+     * `surfaceMode` is `'auto'` (the `defineSkill` default). Per-skill
+     * `surfaceMode` always wins; this is the fallback BEFORE the global
+     * `resolveSurfaceMode(provider, model)` rule.
+     *
+     * Use case: a registry shared across agents pointed at the same
+     * provider can lock surfaceMode here once instead of repeating it
+     * on every `defineSkill`.
+     */
+    readonly surfaceMode?: SurfaceMode;
+    /**
+     * Provider name used as a hint when resolving `surfaceMode: 'auto'`
+     * inside this registry. Most consumers don't set this — runtime code
+     * passes the provider name into `resolveForSkill(skill, provider, model)`
+     * directly. This field is for cases where the registry is composed
+     * far from the agent (test fixtures, design-time inspectors).
+     *
+     * Match the provider's `name` field — `'anthropic'`, `'openai'`,
+     * `'mock'`, etc.
+     */
+    readonly providerHint?: string;
+}
+export declare class SkillRegistry {
+    private readonly skills;
+    private readonly opts;
+    /**
+     * Construct an empty registry. Optional `{ surfaceMode, providerHint }`
+     * fields set registry-level defaults; absent both, the registry is a
+     * pure container (the v2.4 surface).
+     */
+    constructor(opts?: SkillRegistryOptions);
+    /** Registry-level default `surfaceMode`, or `undefined` if unset. */
+    get surfaceMode(): SurfaceMode | undefined;
+    /** Registry-level provider hint, or `undefined` if unset. */
+    get providerHint(): string | undefined;
+    /**
+     * Register a skill. Throws if `skill.flavor !== 'skill'` or if a
+     * skill with the same id is already registered (use `.replace(...)`
+     * to overwrite intentionally).
+     */
+    register(skill: Injection): this;
+    /** Replace an existing skill by id. Throws if id is not registered. */
+    replace(id: string, skill: Injection): this;
+    /** Remove a skill by id. No-op if not registered. */
+    unregister(id: string): this;
+    /** Look up by id. Returns undefined if not registered. */
+    get(id: string): Injection | undefined;
+    /** True iff a skill with the given id is registered. */
+    has(id: string): boolean;
+    /** All registered skills. Order matches registration order. */
+    list(): readonly Injection[];
+    /** Number of registered skills. */
+    get size(): number;
+    /** Drop all registrations. */
+    clear(): void;
+    /**
+     * Materialize the LLM-facing skill discovery tools from the current
+     * registry contents. Returns `{ listSkills, readSkill }`:
+     *
+     *   - `list_skills` — no-arg tool the LLM calls to enumerate
+     *     `{ id, description }` for every registered skill. Lets the
+     *     LLM discover skills without paying the prompt-token cost of
+     *     a static catalog in the system prompt.
+     *
+     *   - `read_skill({ id })` — activates the named skill for the
+     *     NEXT iteration. The Agent's tool-calls subflow inspects this
+     *     tool call by name and updates `scope.activatedInjectionIds`
+     *     so the InjectionEngine on iter N+1 includes the skill in the
+     *     active set (body lands in the system slot; gated tools land
+     *     in the tools slot).
+     *
+     * Both entries are `undefined` when the registry is empty — filter
+     * before adding to a tool list:
+     *
+     *   const { listSkills, readSkill } = registry.toTools();
+     *   const tools = [listSkills, readSkill, ...other].filter(Boolean) as Tool[];
+     *
+     * Composes with `gatedTools` from `agentfootprint/tool-providers`
+     * so PermissionPolicy can scope which roles see the skill discovery
+     * surface.
+     *
+     * @returns A `SkillToolPair` (`{ listSkills, readSkill }`).
+     */
+    toTools(): SkillToolPair;
+    /**
+     * Resolve the effective `surfaceMode` for a skill, applying the
+     * cascade:
+     *
+     *   1. If the skill's own `metadata.surfaceMode` is concrete
+     *      (`'system-prompt'` / `'tool-only'` / `'both'`), return it.
+     *      Per-skill explicit choice always wins.
+     *   2. Else if the registry was constructed with a concrete
+     *      `surfaceMode`, return that.
+     *   3. Else delegate to `resolveSurfaceMode(provider, model)` using
+     *      the explicit `provider` arg (or `this.providerHint` if
+     *      omitted). Falls back to `'tool-only'` when no provider is
+     *      known.
+     *
+     * Forward-compat for Block C / v2.5 per-mode runtime routing: the
+     * runtime calls this with the agent's provider + model to decide
+     * how to materialize the skill's body into slots.
+     *
+     * Throws if the skill is not registered (catches typos at the
+     * caller site rather than silently resolving against a stranger).
+     *
+     * @param skillOrId  A registered Skill `Injection` OR its `id`.
+     * @param provider   Provider name override (wins over `providerHint`).
+     * @param model      Model name for the per-provider attention rule.
+     */
+    resolveForSkill(skillOrId: Injection | string, provider?: string, model?: string): Exclude<SurfaceMode, 'auto'>;
+}

package/dist/esm/lib/injection-engine/buildInjectionEngineSubflow.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Injection Engine — subflow builder.
+ *
+ * Pattern: Subflow Builder (returns a FlowChart mountable via
+ *          `addSubFlowChartNext`). Each subflow stands alone.
+ * Role:    Layer-3 context-engineering primitive. Sits BEFORE the
+ *          three slot subflows in any primitive (Agent, LLMCall) that
+ *          uses Injections. Evaluates every Injection's trigger once
+ *          per iteration.
+ *
+ * Four small, readable stages (was one monolithic `evaluate`):
+ *   1. Gather   — snapshot the turn's inputs (iteration, history size,
+ *                 last tool, LLM-activated count). Observability only.
+ *   2. Evaluate — run every trigger → `activeInjections` (the REAL output
+ *                 the slot subflows read). Logic is UNCHANGED from the old
+ *                 single stage: `activeInjections` is byte-identical, so the
+ *                 slots are 100% unaffected. (Safety invariant.)
+ *   3. Route    — partition `activeInjections` into per-slot buckets
+ *                 (`activeByslot`), mirroring how the slots filter. Pure
+ *                 annotation — the slots still do their own filtering.
+ *   4. Delta    — diff this turn's buckets vs last turn's (`slotDelta`):
+ *                 per slot, what activated / deactivated / stayed. The
+ *                 explainability win ("tools +skill X, system-prompt
+ *                 unchanged"). Reads last turn via `priorActiveByslot`
+ *                 carried by the mount's input/output mappers.
+ *
+ * Nothing here SKIPS a slot — Route/Delta only annotate. See
+ * docs (injection-algorithm blog) + memory agentfootprint_slot_plan_review
+ * for why per-turn skip was deferred.
+ *
+ * Emits:   `agentfootprint.context.evaluated` at the Evaluate stage, with
+ *          aggregate metadata. The per-slot route/delta ride visible stage
+ *          STATE (`activeByslot` / `slotDelta`) so the lens reads them from
+ *          the commit log without a new event-type contract.
+ *
+ * Mount with:
+ *   builder.addSubFlowChartNext(
+ *     SUBFLOW_IDS.INJECTION_ENGINE,
+ *     buildInjectionEngineSubflow({ injections }),
+ *     'Injection Engine',
+ *     {
+ *       inputMapper: (parent) => ({
+ *         iteration: parent.iteration,
+ *         userMessage: parent.userMessage,
+ *         history: parent.history,
+ *         lastToolResult: parent.lastToolResult,
+ *         activatedInjectionIds: parent.activatedInjectionIds ?? [],
+ *         priorActiveByslot: parent.activeByslot ?? EMPTY_ACTIVE_BY_SLOT,
+ *       }),
+ *       outputMapper: (sf) => ({
+ *         activeInjections: sf.activeInjections,
+ *         activeByslot: sf.activeByslot, // carried so next turn's Delta can diff
+ *       }),
+ *     },
+ *   )
+ */
+import type { FlowChart } from 'footprintjs';
+import { type ActiveInjection, type Injection, type InjectionContext } from './types.js';
+export interface InjectionEngineConfig {
+    /**
+     * The Injection list. Frozen at build time. To change at runtime,
+     * rebuild the agent / chart — the primitive is intentionally
+     * declarative.
+     */
+    readonly injections: readonly Injection[];
+    /**
+     * The skill-graph CURSOR resolver (`graph.nextSkill`), present only when the
+     * agent was built with `.skillGraph()`. The Evaluate stage advances the cursor
+     * with the SAME `ctx` the triggers gate on, so trigger ↔ cursor never diverge
+     * (the keystone). Absent → `currentSkillId` is never written (no graph routing).
+     */
+    readonly nextSkill?: (ctx: InjectionContext) => string | undefined;
+}
+/** One routed entry per (active injection × slot it contributes to). */
+export interface RoutedInjection {
+    readonly id: string;
+    readonly source: ActiveInjection['flavor'];
+    readonly reason: string;
+}
+/** Active injections partitioned by the slot they contribute to. */
+export interface ActiveBySlot {
+    readonly systemPrompt: readonly RoutedInjection[];
+    readonly messages: readonly RoutedInjection[];
+    readonly tools: readonly RoutedInjection[];
+}
+/** Per-slot change since last turn. */
+export interface SlotDeltaEntry {
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+    readonly kept: readonly string[];
+}
+/** Per-slot delta across the whole context. */
+export interface SlotDelta {
+    readonly systemPrompt: SlotDeltaEntry;
+    readonly messages: SlotDeltaEntry;
+    readonly tools: SlotDeltaEntry;
+}
+/** Empty buckets — turn-1 prior, and the safe default for the mappers. */
+export declare const EMPTY_ACTIVE_BY_SLOT: ActiveBySlot;
+/**
+ * Build the Injection Engine subflow — Gather → Evaluate → Route → Delta.
+ */
+export declare function buildInjectionEngineSubflow(config: InjectionEngineConfig): FlowChart;
+/** Partition active injections by the slot(s) each contributes to. Mirrors
+ *  the slot subflows' own filters so this view matches what they compose.
+ *  Pure — exported for unit tests + reuse (e.g. the lens). */
+export declare function routeActiveInjections(active: readonly ActiveInjection[]): ActiveBySlot;
+/** Diff two per-slot snapshots into a per-slot delta. Pure — exported for
+ *  unit tests + reuse. */
+export declare function diffActiveBySlot(prior: ActiveBySlot, current: ActiveBySlot): SlotDelta;

package/dist/esm/lib/injection-engine/buildInjectionEngineSubflow.js

@@ -101,6 +101,7 @@ function makeEvaluateStage(injections, nextSkill) {
             activatedInjectionIds: args.activatedInjectionIds ?? [],
             ...(args.currentSkillId !== undefined && { currentSkillId: args.currentSkillId }),
             ...(args.entryScores !== undefined && { entryScores: args.entryScores }),
+            ...(args.entryScorer !== undefined && { entryScorer: args.entryScorer }),
         };
         // KEYSTONE cursor advance — derive the next cursor from the SAME ctx the
         // route triggers gate on (`nextSkill(ctx) === id`), so the active set and the

package/dist/esm/lib/injection-engine/buildInjectionEngineSubflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"buildInjectionEngineSubflow.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/buildInjectionEngineSubflow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"buildInjectionEngineSubflow.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/buildInjectionEngineSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,sBAAsB,GAIvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,wBAAwB,EAAqB,MAAM,iBAAiB,CAAC;AAgD9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,oBAAoB,GAAiB;IAChD,YAAY,EAAE,EAAE;IAChB,QAAQ,EAAE,EAAE;IACZ,KAAK,EAAE,EAAE;CACV,CAAC;AAyBF;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAA6B;IACvE,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IAErC,OAAO,SAAS,CAAuB,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE;QACtE,WAAW,EACT,sFAAsF;KACzF,CAAC;SACC,WAAW,CACV,UAAU,EACV,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,EAC/C,UAAU,EACV,uEAAuE,CACxE;SACA,WAAW,CACV,OAAO,EACP,UAAU,EACV,OAAO,EACP,sFAAsF,CACvF;SACA,WAAW,CACV,OAAO,EACP,UAAU,EACV,OAAO,EACP,oEAAoE,CACrE;SACA,KAAK,EAAE,CAAC;AACb,CAAC;AAED,4EAA4E;AAE5E,4EAA4E;AAC5E,SAAS,WAAW,CAAC,KAAuC;IAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,EAAuB,CAAC;IACnD,KAAK,CAAC,SAAS,CAAC,yBAAyB,EAAE;QACzC,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC;QAC9B,aAAa,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;QACxC,YAAY,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ;QAC3C,uBAAuB,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,IAAI,CAAC;KACjE,CAAC,CAAC;AACL,CAAC;AAED,4EAA4E;AAE5E,SAAS,iBAAiB,CACxB,UAAgC,EAChC,SAAyD;IAEzD,OAAO,CAAC,KAAuC,EAAQ,EAAE;QACvD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,EAAuB,CAAC;QAEnD,MAAM,GAAG,GAAqB;YAC5B,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC;YAC9B,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE;YACnC,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE;YAC3B,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;YACnE,qBAAqB,EAAE,IAAI,CAAC,qBAAqB,IAAI,EAAE;YACvD,GAAG,CAAC,IAAI,CAAC,cAAc,KAAK,SAAS,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;YACjF,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;YACxE,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;SACzE,CAAC;QAEF,yEAAyE;QACzE,8EAA8E;QAC9E,qEAAqE;QACrE,2EAA2E;QAC3E,mEAAmE;QACnE,oEAAoE;QACpE,IAAI,SAAS,EAAE,CAAC;YACd,KAAK,CAAC,SAAS,CAAC,iBAAiB,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QACrD,CAAC;QAED,MAAM,UAAU,GAAG,kBAAkB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAEvD,kEAAkE;QAClE,wEAAwE;QACxE,oEAAoE;QACpE,oEAAoE;QACpE,4DAA4D;QAC5D,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;QAClE,KAAK,CAAC,SAAS,CAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,gBAAgB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAEpD,sEAAsE;QACtE,uEAAuE;QACvE,qEAAqE;QACrE,SAAS,CAAC,KAAK,EAAE,kCAAkC,EAAE;YACnD,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM;YACrC,YAAY,EAAE,UAAU,CAAC,OAAO,CAAC,MAAM;YACvC,cAAc,EAAE,UAAU,CAAC,MAAM;YACjC,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,cAAc,EAAE,UAAU,CAAC,OAAO;YAClC,iBAAiB,EAAE,iBAAiB,CAAC,UAAU,CAAC,MAAM,CAAC;YACvD,uEAAuE;YACvE,yEAAyE;YACzE,wCAAwC;YACxC,YAAY,EAAE,cAAc,CAAC,UAAU,CAAC;YACxC,2EAA2E;YAC3E,0EAA0E;YAC1E,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;SAC5B,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;0EAE0E;AAC1E,SAAS,gBAAgB,CAAC,MAA4B;IACpD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;QACrC,MAAM,OAAO,GAAI,GAAG,CAAC,QAAsE,EAAE,CAC3F,wBAAwB,CACzB,CAAC;QACF,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,CAAC;QACxB,OAAO;YACL;gBACE,WAAW,EAAE,GAAG,CAAC,EAAE;gBACnB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI;oBAClB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;iBACtE,CAAC;gBACF,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;gBAC9C,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;gBAC3C,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;gBAChE,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;aAC1D;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,4EAA4E;AAE5E;;8DAE8D;AAC9D,MAAM,UAAU,qBAAqB,CAAC,MAAkC;IACtE,MAAM,YAAY,GAAsB,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,MAAM,KAAK,GAAsB,EAAE,CAAC;IAEpC,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,KAAK,GAAoB;YAC7B,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,UAAU;SAC9D,CAAC;QACF,8DAA8D;QAC9D,yDAAyD;QACzD,IACE,GAAG,CAAC,MAAM,CAAC,YAAY;YACvB,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;YAClC,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,OAAO,IAAI,GAAG,CAAC,WAAW,KAAK,WAAW,CAAC,EAC5D,CAAC;YACD,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChF,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,UAAU,CAAC,KAAuC;IACzD,MAAM,MAAM,GACT,KAAK,CAAC,SAAS,CAAC,kBAAkB,CAA4C,IAAI,EAAE,CAAC;IACxF,KAAK,CAAC,SAAS,CAAC,cAAc,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,4EAA4E;AAE5E;6EAC6E;AAC7E,SAAS,UAAU,CAAC,KAAuC;IACzD,MAAM,OAAO,GACV,KAAK,CAAC,SAAS,CAAC,cAAc,CAA8B,IAAI,oBAAoB,CAAC;IACxF,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAuB,CAAC,iBAAiB,IAAI,oBAAoB,CAAC;IAC9F,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;0BAC0B;AAC1B,MAAM,UAAU,gBAAgB,CAAC,KAAmB,EAAE,OAAqB;IACzE,OAAO;QACL,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC;QAChE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC;QACpD,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,SAAS,QAAQ,CACf,KAAiC,EACjC,OAAmC;IAEnC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrD,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACxD,OAAO,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1D,IAAI,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;KACvD,CAAC;AACJ,CAAC;AAED;6EAC6E;AAC7E,SAAS,cAAc,CACrB,UAAgC;IAEhC,OAAO,UAAU;SACd,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,kBAAkB,EAAE,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,sEAAsE;AACtE,SAAS,iBAAiB,CAAC,MAA4B;IACrD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/esm/lib/injection-engine/entryScorer.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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';
+/** 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.
+ */
+export declare function keywordScorer(options?: {
+    readonly stopWords?: readonly string[];
+}): EntryScorer;
+/**
+ * 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))`.
+ */
+export declare function embeddingScorer(embedder: Embedder): EntryScorer;

package/dist/esm/lib/injection-engine/entryScorer.js

@@ -0,0 +1,172 @@
+/**
+ * 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 { cosineSimilarity } from '../../memory/embedding/cosine.js';
+import { softmax } from './softmax.js';
+/**
+ * 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 function rankEntries(scorerName, candidates, rawScores) {
+    if (candidates.length === 0)
+        return { scorer: scorerName, chosen: undefined, ranked: [] };
+    const safe = rawScores.map((s) => (Number.isFinite(s) ? s : Number.NEGATIVE_INFINITY));
+    const relevances = softmax(safe);
+    const ranked = candidates.map((c, i) => ({
+        id: c.id,
+        score: rawScores[i], // the scorer's RAW output (may be non-finite — honest)
+        relevance: relevances[i],
+    }));
+    // argmax over the SANITIZED scores (declaration order breaks ties) — never over the
+    // raw scores, so a NaN/Inf can't win. Order-preserving with `relevance`.
+    let winner = 0;
+    for (let i = 1; i < safe.length; i++)
+        if (safe[i] > safe[winner])
+            winner = i;
+    return { scorer: scorerName, chosen: ranked[winner].id, ranked };
+}
+/**
+ * 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.
+ */
+export function keywordScorer(options = {}) {
+    const stop = new Set((options.stopWords ?? DEFAULT_STOP_WORDS).map((w) => w.toLowerCase()));
+    return {
+        name: 'keyword',
+        score({ userMessage, candidates }) {
+            const q = tokenize(userMessage, stop);
+            const scores = candidates.map((c) => setCosine(q, tokenize(c.description, stop)));
+            return rankEntries('keyword', candidates, scores);
+        },
+    };
+}
+/**
+ * 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))`.
+ */
+export function embeddingScorer(embedder) {
+    return {
+        name: 'embedding',
+        async score({ userMessage, candidates }, signal) {
+            if (candidates.length === 0)
+                return { scorer: 'embedding', chosen: undefined, ranked: [] };
+            // One embedBatch round-trip when the backend supports it (OpenAI/Voyage/…),
+            // else N+1 CONCURRENT embed() calls — never the serial N+1 latency stack.
+            const texts = [userMessage, ...candidates.map((c) => c.description)];
+            const sig = signal ? { signal } : {};
+            const [qVec, ...dVecs] = embedder.embedBatch
+                ? await embedder.embedBatch({ texts, ...sig })
+                : await Promise.all(texts.map((text) => embedder.embed({ text, ...sig })));
+            const scores = dVecs.map((dVec) => cosineSimilarity(qVec, dVec));
+            return rankEntries('embedding', candidates, scores);
+        },
+    };
+}
+/** Small, conservative stop list — fillers a user would never route on. */
+const DEFAULT_STOP_WORDS = [
+    'a',
+    'an',
+    'the',
+    'and',
+    'or',
+    'but',
+    'if',
+    'to',
+    'of',
+    'for',
+    'in',
+    'on',
+    'at',
+    'by',
+    'with',
+    'is',
+    'are',
+    'was',
+    'were',
+    'be',
+    'been',
+    'it',
+    'this',
+    'that',
+    'these',
+    'those',
+    'i',
+    'you',
+    'we',
+    'my',
+    'our',
+    'me',
+    'please',
+    'can',
+    'could',
+    'would',
+    'should',
+    'do',
+    'does',
+    'how',
+    'what',
+    'need',
+    'want',
+];
+/**
+ * Lowercase → split on non-alphanumerics → drop 1-char tokens + stop words →
+ * light plural fold → set. The plural fold (drop a single trailing `s` on tokens
+ * length ≥ 4) lets `refund` match `refunds` and `payment` match `payments` — the
+ * common miss that makes a naive keyword router feel broken. Conservative: short
+ * words (`is`, `as`, `bus`) are untouched.
+ */
+function tokenize(text, stop) {
+    const out = new Set();
+    for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length < 2 || stop.has(raw))
+            continue;
+        // Fold a single trailing 's' (refunds→refund) but NOT '-ss' (address stays
+        // address) — that asymmetry would defeat the matching it's for. ASCII only:
+        // non-Latin/accented text is split away by the regex, so the keyword router is
+        // effectively English/ASCII (use embeddingScorer for other languages).
+        const fold = raw.length >= 4 && raw.endsWith('s') && !raw.endsWith('ss');
+        out.add(fold ? raw.slice(0, -1) : raw);
+    }
+    return out;
+}
+/** |A ∩ B| / sqrt(|A| · |B|) — set cosine, 0..1. Empty either side → 0. */
+function setCosine(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+    let shared = 0;
+    for (const t of small)
+        if (large.has(t))
+            shared += 1;
+    return shared / Math.sqrt(a.size * b.size);
+}
+//# sourceMappingURL=entryScorer.js.map

package/dist/esm/lib/injection-engine/entryScorer.js.map

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

package/dist/esm/lib/injection-engine/evaluator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Injection Engine — evaluator.
+ *
+ * Pattern: Pure function. Stateless.
+ * Role:    Internal helper. Called once per iteration by the
+ *          InjectionEngine subflow's compose stage. Slot subflows
+ *          read the `active` array and filter by their slot target.
+ * Emits:   N/A. Caller (the subflow) emits
+ *          `agentfootprint.context.evaluated`.
+ *
+ * Behavior per trigger kind:
+ *   • `always`             → always active.
+ *   • `rule`               → predicate runs against `ctx`. Errors are
+ *                            caught + reported in `skipped`; never
+ *                            propagate. Run never crashes.
+ *   • `on-tool-return`     → active when `ctx.lastToolResult.toolName`
+ *                            matches `trigger.toolName` (string equal
+ *                            or regex test).
+ *   • `llm-activated`      → active when the Injection's `id` is in
+ *                            `ctx.activatedInjectionIds` (the LLM
+ *                            previously called `viaToolName(<id>)`).
+ */
+import type { Injection, InjectionContext, InjectionEvaluation } from './types.js';
+export declare function evaluateInjections(injections: readonly Injection[], ctx: InjectionContext): InjectionEvaluation;

package/dist/esm/lib/injection-engine/factories/defineFact.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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: targets `systemPrompt` OR `messages` (consumer chooses)
+ *
+ * @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()}`,
+ *     slot: 'messages',
+ *     role: 'system',
+ *   });
+ */
+import type { ContextRole } from '../../../events/types.js';
+import type { Injection, InjectionContext } from '../types.js';
+import type { CachePolicy } from '../../../cache/types.js';
+export interface DefineFactOptions {
+    readonly id: string;
+    readonly description?: string;
+    /** The fact (data string) to inject. */
+    readonly data: string;
+    /**
+     * Which slot to land in. Default `'system-prompt'` (most common —
+     * facts the model should always have in mind).
+     * `'messages'` for facts that should appear inline with the
+     * conversation history (use sparingly — increases token cost).
+     */
+    readonly slot?: 'system-prompt' | 'messages';
+    /** When `slot: 'messages'`, the role to use. Default `'system'`. */
+    readonly role?: ContextRole;
+    /**
+     * 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;
+}
+export declare function defineFact(opts: DefineFactOptions): Injection;