agentfootprint 6.43.0 → 6.45.0

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

@@ -0,0 +1,41 @@
+/**
+ * defineInjection — the unified injection factory (one factory, a `type`
+ * discriminant for the flavor).
+ *
+ * The named factories (`defineInstruction`, `defineSkill`, `defineSteering`,
+ * `defineFact`) are self-documenting sugar — prefer them when you know the
+ * flavor at author time. `defineInjection` is for the cases where the flavor is
+ * chosen *programmatically* (config-driven pipelines, a UI that lets users add
+ * any flavor, table-driven tests) — pass `type` and the same options the named
+ * factory takes:
+ *
+ * @example
+ *   // these two are equivalent
+ *   defineInstruction({ id: 'calm', prompt: '…', activeWhen });
+ *   defineInjection({ type: 'instruction', id: 'calm', prompt: '…', activeWhen });
+ *
+ * @example  // flavor decided at runtime
+ *   const inj = defineInjection({ type: cfg.flavor, id: cfg.id, ...cfg.opts });
+ *
+ * All four flavors return the same `Injection` primitive — `type` simply routes
+ * to the matching named factory. RAG and Memory are NOT covered here: they are
+ * separate subsystems (retrieval + stores), not plain Injections.
+ */
+import type { Injection } from '../types.js';
+import { type DefineFactOptions } from './defineFact.js';
+import { type DefineInstructionOptions } from './defineInstruction.js';
+import { type DefineSkillOptions } from './defineSkill.js';
+import { type DefineSteeringOptions } from './defineSteering.js';
+/** Discriminated union — `type` picks the flavor; the rest are that flavor's options. */
+export type DefineInjectionOptions = ({
+    type: 'instruction';
+} & DefineInstructionOptions) | ({
+    type: 'skill';
+} & DefineSkillOptions) | ({
+    type: 'steering';
+} & DefineSteeringOptions) | ({
+    type: 'fact';
+} & DefineFactOptions);
+/** The flavor discriminants `defineInjection` accepts. */
+export type InjectionFlavor = DefineInjectionOptions['type'];
+export declare function defineInjection(opts: DefineInjectionOptions): Injection;

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

@@ -0,0 +1,78 @@
+/**
+ * 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 }`
+ *
+ * @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 { ContextRole } from '../../../events/types.js';
+import type { Injection, InjectionContext } from '../types.js';
+import type { CachePolicy } from '../../../cache/types.js';
+export interface DefineInstructionOptions {
+    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;
+    /** Instruction text. Lands in the slot specified by `slot` (default system-prompt). */
+    readonly prompt: string;
+    /**
+     * Where the instruction lands.
+     *
+     * - `'system-prompt'` (default) — appended to the system prompt.
+     *   Lower attention than recent messages but always available.
+     * - `'messages'` — appended as a recent message. **Higher attention
+     *   weight** — the LLM reads recent messages more carefully than
+     *   system-prompt text. Use this for guidance that MUST be salient
+     *   on this turn (post-tool-result reminders, urgent corrections).
+     *
+     * Same instruction object can target both slots in different agents
+     * — the trigger semantics don't change.
+     */
+    readonly slot?: 'system-prompt' | 'messages';
+    /**
+     * When `slot: 'messages'`, the role to use. Default `'system'`.
+     * `'user'` is also valid; `'assistant'` and `'tool'` work in
+     * principle but rarely make pedagogical sense.
+     */
+    readonly role?: ContextRole;
+    /**
+     * 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;
+}
+export declare function defineInstruction(opts: DefineInstructionOptions): Injection;

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

@@ -0,0 +1,26 @@
+/**
+ * defineRelevanceHint — an advisory system-prompt note for an ambiguous entry.
+ *
+ * When `entryByRelevance()` picks the starting skill but the top candidates are a
+ * NEAR-TIE under the relevance scorer, this injection drops a NON-BINDING note into
+ * the system prompt for that turn: "an offline scorer found these close; it can't
+ * see the conversation — use your own judgment." A hint, not an order.
+ *
+ * Anti-anchoring is the point (the proxy is a rough keyword match, not the model's
+ * own reasoning), so the note is framed as advisory and only fires on a real tie.
+ * It rides the normal injection path (`context.evaluated`) — no new event. Reads
+ * `ctx.entryScores` (set by the PickEntry stage), so it needs `.entryByRelevance()`.
+ *
+ * Add it explicitly: `Agent.create(...).skillGraph(graph).injection(defineRelevanceHint())`.
+ */
+import type { Injection } from '../types.js';
+export interface RelevanceHintOptions {
+    /** Injection id (default `'relevance-hint'`). */
+    readonly id?: string;
+    /**
+     * Near-tie threshold: the hint fires when (top relevance − 2nd relevance) is
+     * below this. Default `0.15` (relevances are softmax shares summing to 1).
+     */
+    readonly threshold?: number;
+}
+export declare function defineRelevanceHint(options?: RelevanceHintOptions): Injection;

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

@@ -0,0 +1,160 @@
+/**
+ * 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
+ * unlocked tools. The LLM decides when a Skill is needed by calling
+ * a designated activation tool — by default `read_skill(<id>)`.
+ *
+ * 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 + tools land
+ * in the slot subflows.
+ *
+ * @example
+ *   const billingSkill = defineSkill({
+ *     id: 'billing',
+ *     description: 'Use for refunds, charges, billing questions.',
+ *     body: 'When handling billing: confirm identity first, then…',
+ *     tools: [refundTool, chargeHistoryTool],
+ *   });
+ */
+import type { Injection } from '../types.js';
+import type { Tool } from '../../../core/tools.js';
+import type { CachePolicy } from '../../../cache/types.js';
+/**
+ * Where the Skill's body lands when activated.
+ *
+ * - `'system-prompt'` — body appended to the system slot on the
+ *   iteration after activation. Best on Claude ≥ 3.5 (training-time
+ *   adherence to system-prompt instructions is strong).
+ * - `'tool-only'` — body delivered ONLY via the `read_skill` tool's
+ *   result. Recency-first by protocol; doesn't rely on the model's
+ *   training to honor system-prompt anchoring. Default for every
+ *   non-Claude provider.
+ * - `'both'` — body lands in both the system slot AND the tool result.
+ *   Belt-and-suspenders for high-stakes Skills on long-context runs.
+ * - `'auto'` — the library picks per provider via `resolveSurfaceMode`.
+ *   `'both'` on Claude ≥ 3.5; `'tool-only'` everywhere else.
+ *
+ * **v2.5 runtime dispatch (Block C):** modes now route differently:
+ *   - `'system-prompt'` → body in system slot, tool result is confirmation
+ *   - `'tool-only'`     → body SUPPRESSED from system slot, tool result IS the body
+ *   - `'both'`          → body in system slot AND in tool result
+ *   - `'auto'`          → keeps v2.4 behavior (body in system slot, tool result is confirmation)
+ *     The Block A4 cascade resolves `'auto'` against provider/model context
+ *     at a future runtime layer (Claude ≥ 3.5 → `'both'`; else `'tool-only'`).
+ */
+export type SurfaceMode = 'auto' | 'system-prompt' | 'tool-only' | 'both';
+/**
+ * When (if ever) to re-deliver a Skill's body in long-running runs.
+ *
+ * Even on providers with strong system-prompt adherence, attention to
+ * the system slot decays past long contexts. `refreshPolicy` re-injects
+ * the body via tool result past a token threshold so the LLM sees it
+ * fresh again.
+ *
+ * **v2.4 status:** the field is reserved + typed; the runtime hook
+ * lands in v2.5 as part of the long-context attention work. Specifying
+ * `refreshPolicy` today is non-breaking — the engine ignores it until
+ * the hook is implemented.
+ */
+export interface RefreshPolicy {
+    /**
+     * Re-inject the Skill body once the run has consumed this many input
+     * tokens since the Skill was last surfaced. Recommended: 50_000 for
+     * 200k-context models; 20_000 for 32k-context models.
+     */
+    readonly afterTokens: number;
+    /**
+     * How to re-inject. `'tool-result'` synthesizes a fresh tool result
+     * carrying the body text (recency-first). Other modes reserved.
+     */
+    readonly via: 'tool-result';
+}
+export interface DefineSkillOptions {
+    readonly id: string;
+    /** Visible to the LLM via the activation tool's description. */
+    readonly description: string;
+    /** Body appended to the system-prompt slot once activated. */
+    readonly body: string;
+    /** Optional unlocked tools, added to the tools slot once activated. */
+    readonly tools?: readonly Tool[];
+    /**
+     * Override the activation tool name. Defaults to `'read_skill'`.
+     * Multiple Skills sharing one activation tool is the common pattern;
+     * the LLM picks WHICH skill via the tool's argument.
+     */
+    readonly viaToolName?: string;
+    /**
+     * Where the body lands when activated. See `SurfaceMode`. Default
+     * `'auto'` — the library resolves per provider via `resolveSurfaceMode`.
+     */
+    readonly surfaceMode?: SurfaceMode;
+    /**
+     * Re-deliver the body past a token threshold to defend against
+     * long-context attention decay. Default: undefined (no refresh).
+     */
+    readonly refreshPolicy?: RefreshPolicy;
+    /**
+     * Per-skill tool gating intent. Block A5 / v2.5.
+     *
+     * - `'currentSkill'` — when this Skill is the only active one, the
+     *   agent's tool list should narrow to this Skill's `tools` (plus
+     *   the consumer-composed baseline). Used with
+     *   `skillScopedTools(id, tools)` from `agentfootprint/tool-providers`
+     *   to materialize the gate. Block C wires this into the runtime
+     *   automatically.
+     * - `undefined` (default) — current additive behavior: this Skill's
+     *   tools are added to the agent's registry on activation, alongside
+     *   every other tool already registered.
+     *
+     * The field is a forward-compat marker today: the metadata stores
+     * it; consumers can read `skill.metadata.autoActivate` to drive
+     * their own ToolProvider composition. v2.5 runtime wiring builds
+     * on this contract without API change.
+     */
+    readonly autoActivate?: AutoActivateMode;
+    /**
+     * Cache policy for this skill's body. Defaults to `'while-active'` —
+     * the body caches while the skill is in `activeInjections[]` (i.e.,
+     * while it's the most-recently-activated skill); invalidates the
+     * moment it deactivates.
+     *
+     * For skills with stable, frequently-accessed bodies, consider
+     * `'always'` to keep the body cached even when temporarily inactive.
+     * For skills with bodies that depend on per-iter state, use
+     * `'never'` or `{ until: ... }`.
+     *
+     * See `CachePolicy` in `agentfootprint/src/cache/types.ts`.
+     */
+    readonly cache?: CachePolicy;
+}
+/**
+ * Per-skill tool gating mode. See `DefineSkillOptions.autoActivate`.
+ *
+ * Reserved future values: `'always'` (always show this Skill's tools
+ * regardless of activation), `'group'` (gate by a named skill group).
+ */
+export type AutoActivateMode = 'currentSkill';
+/**
+ * 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.
+ */
+export declare function resolveSurfaceMode(provider: string, model?: string): SurfaceMode;
+export declare function defineSkill(opts: DefineSkillOptions): Injection;

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

@@ -0,0 +1,39 @@
+/**
+ * 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.',
+ *   });
+ */
+import type { Injection } from '../types.js';
+import type { CachePolicy } from '../../../cache/types.js';
+export interface DefineSteeringOptions {
+    readonly id: string;
+    readonly description?: string;
+    /** Always-on text appended to the system-prompt slot. */
+    readonly prompt: string;
+    /**
+     * Cache policy for this steering injection. Defaults to `'always'`
+     * — steering is by definition always-on stable content, ideal for
+     * provider-side caching. Override with `'never'` if the prompt
+     * contains volatile content (timestamps, per-request IDs).
+     *
+     * See `CachePolicy` in `agentfootprint/src/cache/types.ts` for all
+     * variants. The CacheDecision subflow reads this from
+     * `injection.metadata.cache` each iteration.
+     */
+    readonly cache?: CachePolicy;
+}
+export declare function defineSteering(opts: DefineSteeringOptions): Injection;

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

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+export type { Injection, InjectionTrigger, InjectionContent, InjectionContext, InjectionEvaluation, ActiveInjection, } from './types.js';
+export { projectActiveInjection } from './types.js';
+export { evaluateInjections } from './evaluator.js';
+export { buildInjectionEngineSubflow, type InjectionEngineConfig, } from './buildInjectionEngineSubflow.js';
+export { defineInstruction, type DefineInstructionOptions } from './factories/defineInstruction.js';
+export { defineRelevanceHint, type RelevanceHintOptions } from './factories/defineRelevanceHint.js';
+export { defineSkill, resolveSurfaceMode, type DefineSkillOptions, type SurfaceMode, type RefreshPolicy, type AutoActivateMode, } from './factories/defineSkill.js';
+export { SkillRegistry, type SkillRegistryOptions } from './SkillRegistry.js';
+export { buildListSkillsTool, buildReadSkillTool, type SkillToolPair } from './skillTools.js';
+export { defineSteering, type DefineSteeringOptions } from './factories/defineSteering.js';
+export { defineFact, type DefineFactOptions } from './factories/defineFact.js';
+export { defineInjection, type DefineInjectionOptions, type InjectionFlavor, } from './factories/defineInjection.js';
+export { skillGraph, decide, SKILL_GRAPH_METADATA_KEY, type SkillGraph, type SkillGraphBuilder, type SkillRouteOptions, type SkillEntryOptions, type TreeOptions, type SkillEdge, type SkillEdgeKind, type SkillNode, type DecisionNode, type SkillRouting, type SkillRoutingStep, type EntryScore, type EntryScoring, type SkillGraphConfig, type BuildOptions, type GraphCheckMode, type GraphCheckup, type GraphProblem, type GraphProblemCode, } from './skillGraph.js';
+export { keywordScorer, embeddingScorer, rankEntries, type EntryScorer, type EntryScorerInput, type EntryCandidate, } from './entryScorer.js';
+export { checkSkillContract, checkSkillContracts, skillToolNames } from './skillContract.js';

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

@@ -29,5 +29,6 @@ export { defineInjection, } from './factories/defineInjection.js';
 // Declarative skill graph (proposal 002) — declare skills + routing edges →
 // graph-derived triggers + a drawable topology. Sugar over the trigger model.
 export { skillGraph, decide, SKILL_GRAPH_METADATA_KEY, } from './skillGraph.js';
+export { keywordScorer, embeddingScorer, rankEntries, } from './entryScorer.js';
 export { checkSkillContract, checkSkillContracts, skillToolNames } from './skillContract.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,+DAA+D;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,SAAS;AACT,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,2BAA2B,GAE5B,MAAM,kCAAkC,CAAC;AAE1C,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAiC,MAAM,kCAAkC,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAA6B,MAAM,oCAAoC,CAAC;AAEpG,OAAO,EACL,WAAW,EACX,kBAAkB,GAKnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAE9E,wEAAwE;AACxE,sEAAsE;AACtE,iEAAiE;AACjE,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAsB,MAAM,iBAAiB,CAAC;AAE9F,OAAO,EAAE,cAAc,EAA8B,MAAM,+BAA+B,CAAC;AAE3F,OAAO,EAAE,UAAU,EAA0B,MAAM,2BAA2B,CAAC;AAE/E,6EAA6E;AAC7E,0EAA0E;AAC1E,qDAAqD;AACrD,OAAO,EACL,eAAe,GAGhB,MAAM,gCAAgC,CAAC;AAExC,4EAA4E;AAC5E,8EAA8E;AAC9E,OAAO,EACL,UAAU,EACV,MAAM,EACN,wBAAwB,GAoBzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,+DAA+D;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,SAAS;AACT,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,2BAA2B,GAE5B,MAAM,kCAAkC,CAAC;AAE1C,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAiC,MAAM,kCAAkC,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAA6B,MAAM,oCAAoC,CAAC;AAEpG,OAAO,EACL,WAAW,EACX,kBAAkB,GAKnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAE9E,wEAAwE;AACxE,sEAAsE;AACtE,iEAAiE;AACjE,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAsB,MAAM,iBAAiB,CAAC;AAE9F,OAAO,EAAE,cAAc,EAA8B,MAAM,+BAA+B,CAAC;AAE3F,OAAO,EAAE,UAAU,EAA0B,MAAM,2BAA2B,CAAC;AAE/E,6EAA6E;AAC7E,0EAA0E;AAC1E,qDAAqD;AACrD,OAAO,EACL,eAAe,GAGhB,MAAM,gCAAgC,CAAC;AAExC,4EAA4E;AAC5E,8EAA8E;AAC9E,OAAO,EACL,UAAU,EACV,MAAM,EACN,wBAAwB,GAoBzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,GAIZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,29 @@
+/**
+ * Skill-body ↔ tool-contract consistency check (Proposal 009, Tier 1).
+ *
+ * A skill's `body` (prose injected into the system prompt) can quietly contradict
+ * the tools it actually unlocks, and the model then **refuses a tool that is right
+ * there** — or is told about one it can't call. The library already knows each
+ * skill's real tool set (`inject.tools`), so it can flag the mismatch at authoring
+ * time instead of at run time.
+ *
+ * Tier 1 is DETERMINISTIC (no LLM): pure string + schema checks. The semantic
+ * contradictions it can't see — e.g. "the body calls an OPTIONAL arg required" —
+ * are Tier 2 (LLM-advisory, opt-in). Both checks here are WARNINGS, never errors:
+ * a body naming a foreign tool is often an intentional `read_skill` handoff hint.
+ */
+import type { Injection } from './types.js';
+import type { GraphProblem } from './skillGraphCheckup.js';
+/** The tool names a skill unlocks (`inject.tools[].schema.name`). */
+export declare function skillToolNames(skill: Injection): readonly string[];
+/**
+ * Check ONE skill's body against its tool contract. Pure + side-effect-free.
+ *
+ * @param skill           the skill to check
+ * @param knownToolNames  every tool name reachable in the wider graph/agent (lets
+ *                        the check tell a cross-skill HANDOFF from a typo). Omit to
+ *                        check a skill in isolation (only its own tools are "known").
+ */
+export declare function checkSkillContract(skill: Injection, knownToolNames?: ReadonlySet<string>): GraphProblem[];
+/** Run the contract check across many skills with a shared known-tool set. Pure. */
+export declare function checkSkillContracts(skills: readonly Injection[]): GraphProblem[];