agentfootprint 6.44.0 → 6.45.0

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

@@ -0,0 +1,11 @@
+/**
+ * softmax — numerically-stable softmax over raw scores.
+ *
+ * Used by `skillGraph().entryByRelevance(embedder)` to turn per-entry cosine
+ * similarities into a relevance distribution (the surfaced `relevance` %): the
+ * shares sum to 1, so they read as "how much of the match each entry owns".
+ * Internal helper — not a public export (the public surface is `relevance`).
+ *
+ * `temperature > 0` sharpens (<1) or flattens (>1) the distribution; default 1.
+ */
+export declare function softmax(scores: readonly number[], temperature?: number): number[];

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

@@ -0,0 +1,229 @@
+/**
+ * Injection Engine — types.
+ *
+ * THE primitive that unifies every form of context engineering in the
+ * library. Skills, Steering docs, Instructions, RAG, Memory, custom
+ * Context — all reduce to one shape: an `Injection` with a `trigger`
+ * (when), `inject` (what — one or more slot targets), and a `flavor`
+ * (observability tag).
+ *
+ * Pattern: Strategy (GoF) — each Injection's trigger is a strategy for
+ *          "should I activate this iteration?". Each Injection's
+ *          `inject` is the Memento (GoF) carrying content to slots.
+ * Role:    Layer-3 context engineering primitive in the stack.
+ *          Sits below the slot subflows.
+ * Emits:   Engine emits `agentfootprint.context.evaluated` once per
+ *          iteration. Slot subflows emit `agentfootprint.context.injected`
+ *          for each InjectionRecord they place.
+ */
+import type { Tool } from '../../core/tools.js';
+import type { ContextRole, ContextSource } from '../../events/types.js';
+/**
+ * Discriminated union — exactly one of four kinds. Adding a new
+ * trigger kind is one new variant; engine evaluator + Lens chip
+ * naturally extend.
+ */
+export type InjectionTrigger = 
+/** Always-on. Used for steering-doc-style injections. */
+{
+    readonly kind: 'always';
+}
+/** Predicate runs once per iteration. Most flexible. */
+ | {
+    readonly kind: 'rule';
+    readonly activeWhen: (ctx: InjectionContext) => boolean;
+}
+/** Activates after a specific tool returns. The "Dynamic ReAct" flavor —
+ *  tool results steer the next iteration's prompt. `toolName` matches
+ *  literally (string) or by regex. */
+ | {
+    readonly kind: 'on-tool-return';
+    readonly toolName: string | RegExp;
+}
+/** Activates when the LLM calls a designated tool. The "Skill" flavor:
+ *  `read_skill('billing')` activates the billing Skill for the next
+ *  iteration. */
+ | {
+    readonly kind: 'llm-activated';
+    readonly viaToolName: string;
+};
+/**
+ * Multi-slot per Injection. A Skill for example targets BOTH
+ * system-prompt (the body) AND tools (the unlocked capabilities)
+ * in one Injection. Lens displays the same Injection chip across
+ * each slot it lands in.
+ */
+export interface InjectionContent {
+    /** Text appended to the system-prompt slot when active. */
+    readonly systemPrompt?: string;
+    /** Messages prepended to the messages slot when active. */
+    readonly messages?: ReadonlyArray<{
+        readonly role: ContextRole;
+        readonly content: string;
+    }>;
+    /** Tools added to the tools slot when active. */
+    readonly tools?: readonly Tool[];
+}
+/**
+ * Context passed to `rule` predicates. Read-only snapshot of the
+ * agent's iteration state. Internal mutable state is hidden.
+ */
+export interface InjectionContext {
+    /** Current ReAct iteration (1-based). */
+    readonly iteration: number;
+    /** The current user message that started this turn. */
+    readonly userMessage: string;
+    /**
+     * Conversation history up to (but not including) the current
+     * iteration's LLM call. Includes prior iterations within the same turn.
+     */
+    readonly history: ReadonlyArray<{
+        readonly role: ContextRole;
+        readonly content: string;
+        readonly toolName?: string;
+    }>;
+    /**
+     * The most recent tool result, if the previous iteration ended in a
+     * tool call. Used both by `rule` predicates and by `on-tool-return`
+     * trigger evaluation.
+     */
+    readonly lastToolResult?: {
+        readonly toolName: string;
+        readonly result: string;
+    };
+    /**
+     * IDs of LLM-activated injections that the LLM has activated this
+     * turn (via their `viaToolName` tool call). Engine includes them
+     * in the active set on subsequent iterations until turn end.
+     */
+    readonly activatedInjectionIds: readonly string[];
+    /**
+     * The skill-graph CURSOR — which skill node the graph is currently
+     * *in*, persisted across iterations. Undefined before the first entry
+     * (cold start). `skillGraph()` route edges are `from`-gated against it:
+     * an edge `A → B` only fires while `currentSkillId === 'A'`, which kills
+     * cross-skill edge bleed (an edge firing while in an unrelated skill).
+     *
+     * Set by the loop's cursor-update stage to `graph.nextSkill(ctx)` each
+     * iteration; absent for agents that don't use `skillGraph()`. Plain
+     * `rule`/`always`/`on-tool-return` predicates may ignore it.
+     */
+    readonly currentSkillId?: string;
+    /**
+     * The relevance ranking of entry candidates from an entry scorer (`.entryBy()` /
+     * `.entryByRelevance()`) — written by the PickEntry stage at turn start.
+     * `defineRelevanceHint()` reads it to detect a near-tie. Absent unless the graph
+     * used an entry scorer. `score` is the raw strategy score (cosine / word-overlap);
+     * `relevance` is the softmax share (the surfaced %).
+     */
+    readonly entryScores?: ReadonlyArray<{
+        readonly id: string;
+        readonly score: number;
+        readonly relevance: number;
+    }>;
+    /** Name of the entry scorer that produced `entryScores` (e.g. `'keyword'`,
+     *  `'embedding'`). Absent unless an entry scorer ran. */
+    readonly entryScorer?: string;
+}
+/**
+ * THE primitive. Five fields. Four trigger kinds. Three slot targets.
+ *
+ * Every named flavor (Skill, Steering, Instruction, Context, RAG,
+ * Memory, Guardrail, …) is a sugar factory that produces one of these.
+ *
+ * @example
+ *   // Direct construction (power user)
+ *   const myInjection: Injection = {
+ *     id: 'demo',
+ *     flavor: 'instructions',
+ *     trigger: { kind: 'rule', activeWhen: (ctx) => ctx.iteration > 1 },
+ *     inject: { systemPrompt: 'Refine the previous answer.' },
+ *   };
+ *
+ *   // Sugar (recommended)
+ *   const myInjection2 = defineInstruction({
+ *     id: 'demo',
+ *     activeWhen: (ctx) => ctx.iteration > 1,
+ *     prompt: 'Refine the previous answer.',
+ *   });
+ */
+export interface Injection {
+    /** Unique id. Used for observability + de-duplication + LLM-activation lookup. */
+    readonly id: string;
+    /** Human-readable description (Lens / docs / debug). */
+    readonly description?: string;
+    /** Observability tag. Drives Lens chip color + ContextRecorder source field. */
+    readonly flavor: ContextSource;
+    /** WHEN to activate. */
+    readonly trigger: InjectionTrigger;
+    /** WHAT to contribute (one or more slots). */
+    readonly inject: InjectionContent;
+    /**
+     * Optional flavor-specific metadata. Engine ignores keys it doesn't
+     * recognize; flavor factories use this for opt-in fields without
+     * widening the Injection contract.
+     *
+     * Known keys:
+     *   - `surfaceMode` (Skill) — `'auto' | 'system-prompt' | 'tool-only' | 'both'`
+     *   - `refreshPolicy` (Skill) — `{ afterTokens, via }`
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Returned by `evaluateInjections()`. Slot subflows consume `active`;
+ * `skipped` is observability metadata (predicate errors).
+ */
+export interface InjectionEvaluation {
+    readonly active: readonly Injection[];
+    readonly skipped: ReadonlyArray<{
+        readonly id: string;
+        readonly reason: 'predicate-threw' | 'unknown-trigger-kind';
+        readonly error?: string;
+    }>;
+}
+/**
+ * POJO projection of an active Injection — flows through footprintjs
+ * scope (which cannot serialize functions) so that slot subflows can
+ * read it across the subflow boundary.
+ *
+ * Drops the `trigger` (already evaluated) and projects `inject.tools`
+ * to schemas only (the Tool's `execute` function lives on the Agent's
+ * closure-held registry, looked up by injection id at exec time).
+ */
+export interface ActiveInjection {
+    readonly id: string;
+    readonly flavor: import('../../events/types.js').ContextSource;
+    readonly description?: string;
+    /**
+     * Resolved surfaceMode (Skill flavor only). Drives Block C runtime
+     * dispatch — slot subflows skip system-slot injection when this is
+     * `'tool-only'`; the read_skill tool delivers the body in its
+     * result for `'tool-only'` and `'both'`.
+     *
+     * `'auto'` and absent both mean "keep v2.4 behavior" (body in
+     * system slot, tool result is confirmation only). The Block A4
+     * cascade resolves 'auto' against provider/model context at a
+     * later layer; this projection stays declarative.
+     */
+    readonly surfaceMode?: 'auto' | 'system-prompt' | 'tool-only' | 'both';
+    /**
+     * Per-skill tool gating intent (Skill flavor only). Reserved for
+     * Block C+ runtime auto-wiring of `skillScopedTools`. Today
+     * consumers wire this manually via `agentfootprint/tool-providers`.
+     */
+    readonly autoActivate?: 'currentSkill';
+    readonly inject: {
+        readonly systemPrompt?: string;
+        readonly messages?: ReadonlyArray<{
+            readonly role: import('../../events/types.js').ContextRole;
+            readonly content: string;
+        }>;
+        /** Tool schemas only — `execute` lives on Agent's closure registry. */
+        readonly tools?: ReadonlyArray<{
+            readonly schema: import('../../adapters/types.js').LLMToolSchema;
+            readonly injectionId: string;
+        }>;
+    };
+}
+/** Project a full Injection (with functions) into a scope-safe POJO. */
+export declare function projectActiveInjection(inj: Injection): ActiveInjection;

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

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA6NH,wEAAwE;AACxE,MAAM,UAAU,sBAAsB,CAAC,GAAc;IACnD,qEAAqE;IACrE,yEAAyE;IACzE,uEAAuE;IACvE,MAAM,IAAI,GAAG,GAAG,CAAC,QAAuE,CAAC;IACzF,MAAM,GAAG,GAAoB;QAC3B,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,GAAG,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC;QACxD,GAAG,CAAC,IAAI,EAAE,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAA6C,EAAE,CAAC;QAC7F,GAAG,CAAC,IAAI,EAAE,YAAY,IAAI;YACxB,YAAY,EAAE,IAAI,CAAC,YAA+C;SACnE,CAAC;QACF,MAAM,EAAE;YACN,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;YACzE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YACpF,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI;gBACtB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAClC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE;oBACvB,WAAW,EAAE,GAAG,CAAC,EAAE;iBACpB,CAAC,CAAC;aACJ,CAAC;SACH;KACF,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAkOH,wEAAwE;AACxE,MAAM,UAAU,sBAAsB,CAAC,GAAc;IACnD,qEAAqE;IACrE,yEAAyE;IACzE,uEAAuE;IACvE,MAAM,IAAI,GAAG,GAAG,CAAC,QAAuE,CAAC;IACzF,MAAM,GAAG,GAAoB;QAC3B,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,GAAG,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC;QACxD,GAAG,CAAC,IAAI,EAAE,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAA6C,EAAE,CAAC;QAC7F,GAAG,CAAC,IAAI,EAAE,YAAY,IAAI;YACxB,YAAY,EAAE,IAAI,CAAC,YAA+C;SACnE,CAAC;QACF,MAAM,EAAE;YACN,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;YACzE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YACpF,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI;gBACtB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAClC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE;oBACvB,WAAW,EAAE,GAAG,CAAC,EAAE;iBACpB,CAAC,CAAC;aACJ,CAAC;SACH;KACF,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/esm/lib/lazyRequire.d.ts

@@ -0,0 +1,29 @@
+/**
+ * lazyRequire — module-path-indirect `require()` wrapper for lazy
+ * peer-dep loading.
+ *
+ * Why a wrapper: bundlers (Vite, esbuild, webpack, Rollup) statically
+ * analyze `require('literal-string')` calls and try to resolve the
+ * dependency at BUILD time — even when the function is never called
+ * at runtime. For optional peer-deps (`@modelcontextprotocol/sdk`,
+ * `@anthropic-ai/sdk`, `ioredis`, `@aws-sdk/client-bedrock-*`), this
+ * means consumers who never instantiate the matching adapter still
+ * get a build error if the peer-dep isn't installed.
+ *
+ * Wrapping the call in a function with a string PARAMETER hides the
+ * specifier from static analysis. At runtime this is exactly the
+ * same as inline `require()`, including the throwing behavior when
+ * the peer-dep isn't installed.
+ *
+ * Pattern: indirect require — used by Node's `createRequire`-style
+ *          fallbacks for the same reason.
+ *
+ * @example
+ *   try {
+ *     const mod = lazyRequire<typeof import('ioredis')>('ioredis');
+ *     this._client = new mod.default(...);
+ *   } catch {
+ *     throw new Error('install ioredis to use RedisStore');
+ *   }
+ */
+export declare function lazyRequire<T = unknown>(specifier: string): T;

package/dist/esm/lib/mcp/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP — Model Context Protocol client integration. Connect to an MCP
+ * server, register its tools on your Agent. Server-side support is
+ * separate (consumer exposes their agent as an MCP tool — different
+ * use case, not yet shipped).
+ */
+export { mcpClient } from './mcpClient.js';
+export { mockMcpClient, type MockMcpClientOptions, type MockMcpTool } from './mockMcpClient.js';
+export type { McpClient, McpClientOptions, McpHttpTransport, McpStdioTransport, McpTransport, McpSdkClient, } from './types.js';

package/dist/esm/lib/mcp/mcpClient.d.ts

@@ -0,0 +1,46 @@
+/**
+ * mcpClient — connect to an MCP server, expose its tools to your Agent.
+ *
+ *   const slack = await mcpClient({
+ *     name: 'slack',
+ *     transport: { transport: 'stdio', command: 'npx', args: ['@example/slack-mcp'] },
+ *   });
+ *
+ *   const tools = await slack.tools();   // → readonly Tool[]
+ *   const agent = Agent.create({ ... }).tools(tools).build();
+ *
+ *   // ...
+ *
+ *   await slack.close();
+ *
+ * Pattern: Adapter (GoF) — translates MCP `listTools()` / `callTool()`
+ *          into agentfootprint's `Tool` interface (schema + execute).
+ *          Each MCP tool becomes ONE agentfootprint Tool. The agent's
+ *          existing tool-call handler invokes `client.callTool()`
+ *          inside the wrapped `execute`.
+ *
+ * Role:    Layer-3 integration. Sits next to `defineTool` — same
+ *          shape, different source. Once tools land on the agent,
+ *          the rest of the library doesn't know they came from MCP.
+ *
+ * Emits:   N/A — wrapped tools emit the standard
+ *          `agentfootprint.stream.tool_start` / `tool_end` events
+ *          when the agent calls them. Add `name: '<mcp-server>'` to
+ *          `McpClientOptions` so observability surfaces can group
+ *          tool calls by server.
+ *
+ * Lazy-require pattern: the `@modelcontextprotocol/sdk` peer-dep
+ * loads only when a consumer actually constructs a client. Tests
+ * inject `_client` and skip the import path entirely.
+ */
+import type { McpClient, McpClientOptions } from './types.js';
+/**
+ * Connect to an MCP server. Returns an `McpClient` that exposes the
+ * server's tools as agentfootprint `Tool[]` and a `close()` to tear
+ * down the transport.
+ *
+ * @throws when `@modelcontextprotocol/sdk` is not installed (see
+ *   error message for `npm install` hint), or when the transport
+ *   fails to connect.
+ */
+export declare function mcpClient(opts: McpClientOptions): Promise<McpClient>;

package/dist/esm/lib/mcp/mockMcpClient.d.ts

@@ -0,0 +1,65 @@
+/**
+ * mockMcpClient — in-memory MCP client for development and tests.
+ *
+ *   const slack = mockMcpClient({
+ *     tools: [
+ *       {
+ *         name: 'send_message',
+ *         description: 'Post a message to a channel',
+ *         inputSchema: { type: 'object' },
+ *         handler: async ({ text }) => `Posted: ${text}`,
+ *       },
+ *     ],
+ *   });
+ *
+ *   const agent = Agent.create({ provider: mock({ reply: 'ok' }) })
+ *     .tools(await slack.tools())
+ *     .build();
+ *
+ * Pattern: Adapter (GoF) — produces an `McpClient` with the same shape
+ *          as `mcpClient(opts)` but driven by an in-memory tool table
+ *          instead of the MCP SDK + transport. Drop-in for development:
+ *          start with `mockMcpClient`, swap to `mcpClient` once the
+ *          real server is ready.
+ *
+ * Why public: `mcpClient`'s `_client` injection is `@internal` because
+ * the SDK shape isn't a stable public surface. `mockMcpClient` exposes
+ * a curated tool-handler shape that's tied to OUR Tool contract instead
+ * — stable, documented, and the right level of abstraction for
+ * mock-first development.
+ */
+import type { McpClient } from './types.js';
+/** A scripted tool exposed by the mock MCP server. */
+export interface MockMcpTool {
+    /** Tool name as the LLM sees it. */
+    readonly name: string;
+    /** Description surfaced to the LLM via the tool schema. */
+    readonly description?: string;
+    /**
+     * JSON-schema-like input schema. Passed through to the agent's tool
+     * registry verbatim — same as a real MCP server's `listTools()`.
+     */
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    /**
+     * Async handler that runs when the agent calls this tool. Receives
+     * the args the LLM produced; returns the string result the agent
+     * sees as the tool-result message.
+     *
+     * Defaults to `async () => '[mock result]'` when omitted — useful
+     * when the consumer cares about wiring not behavior.
+     */
+    readonly handler?: (args: Record<string, unknown>) => Promise<string>;
+}
+export interface MockMcpClientOptions {
+    /** Logical server name. Surfaces in observability + error messages. */
+    readonly name?: string;
+    /** Tools exposed by the mock server. */
+    readonly tools: readonly MockMcpTool[];
+}
+/**
+ * Build an in-memory `McpClient`. Useful when you want to develop
+ * against MCP semantics without spawning subprocesses, hitting the
+ * network, or installing `@modelcontextprotocol/sdk`. Same `McpClient`
+ * shape as `mcpClient(opts)` — code that consumes one accepts the other.
+ */
+export declare function mockMcpClient(options: MockMcpClientOptions): McpClient;

package/dist/esm/lib/mcp/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * MCP — Model Context Protocol client integration.
+ *
+ * MCP (https://modelcontextprotocol.io) is an open standard for
+ * connecting LLMs to external tools and data sources. agentfootprint's
+ * MCP adapter is **client-only** — it consumes MCP servers and exposes
+ * their tools as agentfootprint `Tool[]` so consumers can plug them
+ * straight into `agent.tool(...)`.
+ *
+ * Pattern: Adapter (GoF) — translates MCP wire format ↔ agentfootprint
+ *          `Tool` interface. The MCP SDK does the protocol work; we
+ *          just bridge.
+ * Role:    Layer-3 tool integration. Pairs with `defineTool` (the
+ *          inline alternative for non-MCP tools).
+ * Emits:   N/A directly — wrapped tools emit the standard
+ *          `agentfootprint.stream.tool_start` / `tool_end` events
+ *          when the agent calls them.
+ *
+ * Server-side support (exposing an agent or LLMCall as an MCP tool)
+ * is a separate concern not yet shipped. This module covers the
+ * 80% case: pulling an existing MCP server's tools INTO an agent.
+ */
+import type { Tool } from '../../core/tools.js';
+/**
+ * `stdio` transport — spawns a local subprocess and speaks MCP over
+ * its stdin/stdout. Best for development, single-user scenarios, and
+ * testing against locally-installed MCP servers.
+ */
+export interface McpStdioTransport {
+    readonly transport: 'stdio';
+    /** Executable to spawn (e.g., `'npx'`, `'node'`, `'python'`). */
+    readonly command: string;
+    /** CLI args passed to the executable. */
+    readonly args?: readonly string[];
+    /** Optional env vars set on the subprocess. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Working directory for the subprocess. */
+    readonly cwd?: string;
+}
+/**
+ * `http` transport — speaks MCP over Streamable HTTP. Best for remote
+ * servers, web environments, and multi-user scenarios.
+ */
+export interface McpHttpTransport {
+    readonly transport: 'http';
+    /** MCP server endpoint URL. */
+    readonly url: string;
+    /** Optional auth headers (e.g., `Authorization: Bearer ...`). */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export type McpTransport = McpStdioTransport | McpHttpTransport;
+export interface McpClientOptions {
+    /**
+     * Logical name for observability + tool-call routing. Surfaces in
+     * Lens chips and event payloads. Defaults to `'mcp'`. Recommend
+     * setting per-server (`'slack-mcp'`, `'github-mcp'`) when you
+     * connect to multiple servers.
+     */
+    readonly name?: string;
+    /** Transport configuration — stdio or http. */
+    readonly transport: McpTransport;
+    /**
+     * Optional client identity sent on connect. Default:
+     * `{ name: 'agentfootprint', version: <package version> }`.
+     */
+    readonly clientInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** Abort the connection / list / call paths. Honored by the SDK. */
+    readonly signal?: AbortSignal;
+    /**
+     * @internal Pre-built SDK client for tests. Skips SDK import +
+     * transport construction. Same convention as `AnthropicProvider._client`.
+     */
+    readonly _client?: McpSdkClient;
+}
+/**
+ * What `mcpClient(opts)` returns. Connect once; call `.tools()` to
+ * snapshot the tool list, `.refresh()` to re-list after the server's
+ * tools change, `.close()` when done.
+ */
+export interface McpClient {
+    /** Logical name from options (or default `'mcp'`). */
+    readonly name: string;
+    /**
+     * List the server's tools as agentfootprint `Tool[]`. First call
+     * after `mcpClient(...)` is the snapshot used to register on the
+     * agent; subsequent calls re-fetch (cheap, in-memory cached by the
+     * SDK between fetches).
+     */
+    tools(): Promise<readonly Tool[]>;
+    /**
+     * Force a refresh from the server. Use when you suspect the server
+     * has dynamically added/removed tools mid-session (e.g., after the
+     * server processes a config update).
+     */
+    refresh(): Promise<readonly Tool[]>;
+    /** Close the underlying transport. After `close()` the client is unusable. */
+    close(): Promise<void>;
+}
+/**
+ * Minimal structural type capturing the parts of the MCP SDK client
+ * we touch. Defined locally so we can:
+ *   1. Inject a mock for tests (`McpClientOptions._client`)
+ *   2. Avoid a hard import on `@modelcontextprotocol/sdk` (which is
+ *      a lazy peer-dep)
+ *
+ * The real SDK exports a richer surface; we narrow to what's needed.
+ */
+export interface McpSdkClient {
+    connect(transport: unknown): Promise<void>;
+    listTools(): Promise<{
+        readonly tools: ReadonlyArray<{
+            readonly name: string;
+            readonly description?: string;
+            readonly inputSchema: Readonly<Record<string, unknown>>;
+        }>;
+    }>;
+    callTool(args: {
+        readonly name: string;
+        readonly arguments?: Readonly<Record<string, unknown>>;
+        /** Forwarded from `McpClientOptions.signal` so consumers can cancel hung tool calls. */
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly content: ReadonlyArray<{
+            readonly type: string;
+            readonly text?: string;
+        }>;
+        readonly isError?: boolean;
+    }>;
+    close(): Promise<void>;
+}

package/dist/esm/lib/rag/defineRAG.d.ts

@@ -0,0 +1,139 @@
+/**
+ * defineRAG — sugar factory for retrieval-augmented generation.
+ *
+ * RAG is a context-engineering flavor: embed the user's question,
+ * retrieve top-K semantically similar chunks from a vector store,
+ * inject those chunks into the messages slot of the next LLM call.
+ * It's the same plumbing as `defineMemory({ type: SEMANTIC,
+ * strategy: TOP_K })` — the rename is for intent + ergonomics.
+ *
+ *   defineMemory ─┬─► EPISODIC   (raw conversation)
+ *                 ├─► SEMANTIC   (extracted facts / RAG chunks)
+ *                 ├─► NARRATIVE  (beats / summaries)
+ *                 └─► CAUSAL     (footprintjs decision snapshots)
+ *
+ *   defineRAG    ─►  SEMANTIC + TOP_K with RAG-specific defaults
+ *                    (asRole='user', threshold=0.7, no LLM-extract)
+ *
+ * Pattern: Composition over duplication — defineRAG returns a
+ *          MemoryDefinition produced by defineMemory. No new engine
+ *          code, no new slot subflow, no new event type.
+ *
+ * Role:    Layer-3 context-engineering primitive. Lives next to
+ *          defineSkill / defineSteering / defineInstruction / defineFact
+ *          but resolves to a memory subflow rather than an Injection
+ *          (RAG content is computed at runtime via async retrieval —
+ *          can't fit the synchronous Injection.inject shape).
+ *
+ * Emits:   Indirectly — the underlying memory pipeline emits
+ *          `agentfootprint.context.injected` when retrieved chunks
+ *          land in the messages slot.
+ *
+ * @see ./indexDocuments.ts  for the seeding helper
+ * @see ../../memory/define.ts  for the underlying factory
+ *
+ * @example  Basic usage
+ * ```ts
+ * import {
+ *   Agent, defineRAG, indexDocuments, InMemoryStore, mockEmbedder, mock,
+ * } from 'agentfootprint';
+ *
+ * const embedder = mockEmbedder();
+ * const store = new InMemoryStore();
+ *
+ * // Seed the store once at startup
+ * await indexDocuments(store, embedder, [
+ *   { id: 'doc1', content: 'Refunds are processed within 3 business days.' },
+ *   { id: 'doc2', content: 'Pro plan costs $20/month.' },
+ * ]);
+ *
+ * const docs = defineRAG({
+ *   id: 'product-docs',
+ *   description: 'Retrieve product documentation chunks',
+ *   store,
+ *   embedder,
+ *   topK: 3,
+ *   threshold: 0.6,
+ * });
+ *
+ * const agent = Agent.create({ provider: mock({ reply: 'ok' }), model: 'mock' })
+ *   .rag(docs)
+ *   .build();
+ * ```
+ */
+import type { ContextRole } from '../../events/types.js';
+import type { Embedder } from '../../memory/embedding/index.js';
+import type { MemoryStore } from '../../memory/store/index.js';
+import type { MemoryDefinition } from '../../memory/define.types.js';
+export interface DefineRAGOptions {
+    /** Stable id. Becomes the scope-key suffix and the Lens label. */
+    readonly id: string;
+    /**
+     * Human-readable description. Surfaces in narrative + Lens hover.
+     * Recommend describing the *corpus* (e.g., "Product documentation
+     * chunks indexed weekly from docs.example.com").
+     */
+    readonly description?: string;
+    /**
+     * Vector-capable store containing the indexed corpus. Must implement
+     * `search()`. Use `indexDocuments(store, embedder, docs)` at startup
+     * to populate it. Ships with `InMemoryStore` for dev/tests; swap to
+     * `pgvector` / Pinecone / Qdrant adapters in production.
+     */
+    readonly store: MemoryStore;
+    /**
+     * Embedder used for the read-side query. Pass the SAME embedder
+     * instance (or one with the same `name`) that was used for indexing
+     * — cross-model similarity scores are not comparable.
+     */
+    readonly embedder: Embedder;
+    /**
+     * Stable id of the embedder. Stored on entries during indexing
+     * (via `indexDocuments`) and filtered at search time so a later
+     * embedder swap doesn't pollute results.
+     */
+    readonly embedderId?: string;
+    /**
+     * Top-K chunks to retrieve per turn. Default 3 (balanced —
+     * defends against lost-in-the-middle while giving multiple
+     * perspectives). Increase for richer context, decrease for cost.
+     */
+    readonly topK?: number;
+    /**
+     * Minimum cosine similarity to inject. **Strict** — when no chunk
+     * meets the threshold, NO injection happens (no fallback that would
+     * pollute the prompt with weak matches). Default 0.7.
+     *
+     * Tuning note: 0.7 is a high bar for some embedders. Sentence-BERT
+     * relatives (`all-MiniLM-L6-v2`, etc.) often score 0.4–0.6 even on
+     * relevant chunks. If you see frequent zero-result silent skips,
+     * lower to ~0.5 and observe the `agentfootprint.context.injected`
+     * stream. OpenAI `text-embedding-3-*` and Cohere embed-v3 typically
+     * sit comfortably with 0.7.
+     */
+    readonly threshold?: number;
+    /**
+     * Role to use when injecting retrieved chunks into the messages
+     * slot. Default `'user'`.
+     *
+     * Why `'user'`: in tool-using ReAct loops, retrieved chunks
+     * conceptually "augment what the user asked." Anthropic's tool-use
+     * cookbook and OpenAI's RAG cookbook both show retrieved context
+     * inside user-turn messages.
+     *
+     * Use `'system'` for authoritative reference docs that should
+     * outweigh user instruction (policy / compliance / brand-voice
+     * corpora). Use `'assistant'` only if you've persisted prior agent
+     * turns as context — rare.
+     */
+    readonly asRole?: ContextRole;
+}
+/**
+ * Build a RAG context-engineering definition. The returned
+ * `MemoryDefinition` is registered on the Agent via `.rag(definition)`
+ * (or, equivalently, `.memory(definition)` — same plumbing).
+ *
+ * @throws when `store` does not implement `search()`. RAG requires a
+ *         vector-capable adapter.
+ */
+export declare function defineRAG(opts: DefineRAGOptions): MemoryDefinition;