agentfootprint 2.0.1 → 2.2.0

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

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ *
+ * 7-panel review (2026-04-29):
+ * - LLM Systems    ✅  inputSchema preserved verbatim — the LLM sees
+ *                      the same tool schema MCP advertised
+ * - Architect      ✅  pure adapter; no engine code. New tool sources
+ *                      slot in via the same `Tool` interface
+ * - API Designer   ✅  three methods (.tools / .refresh / .close)
+ *                      mirror the MCP SDK lifecycle
+ * - Performance    ✅  tool list cached after first fetch; .refresh
+ *                      is opt-in. callTool round-trip is one network
+ *                      hop per tool call (same as direct LLM-tool flow)
+ * - Privacy        ✅  no implicit logging; consumer controls auth
+ *                      via transport headers
+ * - SoftEng        ✅  lazy-required SDK + friendly install error;
+ *                      mock injection point for tests
+ * - TS Engineer    ✅  structural McpSdkClient shim — works against
+ *                      any future SDK version with the same shape
+ *
+ * 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>;
+//# sourceMappingURL=mcpClient.d.ts.map

package/dist/types/lib/mcp/mcpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAA8B,MAAM,YAAY,CAAC;AAO1F;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CA4B1E"}

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

@@ -0,0 +1,132 @@
+/**
+ * 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>>;
+    }): Promise<{
+        readonly content: ReadonlyArray<{
+            readonly type: string;
+            readonly text?: string;
+        }>;
+        readonly isError?: boolean;
+    }>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ *
+ * 7-panel review (2026-04-29):
+ * - LLM Systems    ✅  injects as 'user' role by default — RAG chunks
+ *                      land where the LLM treats them as authoritative
+ *                      retrieved context, not behavior rules
+ * - Architect      ✅  composition over defineMemory; zero new engine
+ *                      code; multi-RAG layering works via per-id keys
+ * - API Designer   ✅  one factory, mirrors defineMemory shape; consumer
+ *                      ergonomics: `agent.rag(defineRAG({...}))`
+ * - Performance    ✅  embedding cost is one call per turn (TURN_START
+ *                      timing, default); strict threshold prevents
+ *                      injecting low-confidence noise
+ * - Privacy        ✅  multi-tenant via MemoryIdentity tuple; doc
+ *                      content never crosses tenant boundaries
+ * - ML / IR        ✅  embedder version pinned via `embedderId`; cosine
+ *                      score semantics inherited from MemoryStore
+ * - SoftEng        ✅  thin file (this one); existing memory tests
+ *                      cover the underlying pipeline
+ *
+ * @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,
+ * } 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 }).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.
+     */
+    readonly threshold?: number;
+    /**
+     * Role to use when injecting retrieved chunks into the messages
+     * slot. Default `'user'` — RAG chunks are most often treated as
+     * "context the user provided" by LLMs. Use `'system'` for
+     * authoritative reference docs that should outweigh user instruction.
+     */
+    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;
+//# sourceMappingURL=defineRAG.d.ts.map

package/dist/types/lib/rag/defineRAG.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineRAG.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/defineRAG.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CA8BlE"}

package/dist/types/lib/rag/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * RAG — retrieval-augmented generation as a context-engineering
+ * flavor. ONE factory + ONE seeding helper. Composes over the memory
+ * subsystem (semantic + top-K + strict threshold).
+ */
+export { defineRAG, type DefineRAGOptions } from './defineRAG.js';
+export { indexDocuments, type IndexDocumentsOptions, type RagDocument } from './indexDocuments.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/rag/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/types/lib/rag/indexDocuments.d.ts

@@ -0,0 +1,77 @@
+/**
+ * indexDocuments — seed a vector-capable MemoryStore with documents.
+ *
+ * Embeds each document, builds a `MemoryEntry<{content, metadata?}>`,
+ * batches into `store.putMany()`. Used at application startup to
+ * populate a RAG store before the first agent run.
+ *
+ * Pattern: Bulk-write helper. Not a flowchart stage — it runs once
+ *          at boot, not per-iteration.
+ * Role:    Layer-3 RAG pipeline starter. Pairs with `defineRAG()`
+ *          which only does the read side.
+ * Emits:   N/A — startup-time batch write, not part of the agent run.
+ *
+ * @example
+ * ```ts
+ * import { InMemoryStore, mockEmbedder, indexDocuments, defineRAG } from 'agentfootprint';
+ *
+ * const store = new InMemoryStore();
+ * const embedder = mockEmbedder();
+ *
+ * await indexDocuments(store, embedder, [
+ *   { id: 'doc1', content: 'Refunds processed within 3 business days.' },
+ *   { id: 'doc2', content: 'Pro plan: $20/mo, includes priority support.', metadata: { tier: 'pro' } },
+ *   { id: 'doc3', content: 'Free plan: limited to 100 calls/month.' },
+ * ]);
+ *
+ * const docs = defineRAG({ id: 'product-docs', store, embedder });
+ * agent.rag(docs);
+ * ```
+ */
+import type { Embedder } from '../../memory/embedding/index.js';
+import type { MemoryStore } from '../../memory/store/index.js';
+import type { MemoryIdentity } from '../../memory/identity/index.js';
+/** A document to index. `id` must be unique within the store + identity. */
+export interface RagDocument {
+    readonly id: string;
+    readonly content: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface IndexDocumentsOptions {
+    /**
+     * Identity scope to write under. Default: a single shared
+     * `{ conversationId: '_global' }` namespace, suitable for app-wide
+     * corpora. Override for per-tenant document partitions.
+     */
+    readonly identity?: MemoryIdentity;
+    /**
+     * Stable id of the embedder. Stored on each entry so a future
+     * embedder swap doesn't silently mix similarity scores. Default:
+     * `'default-embedder'` — pass an explicit id when you may rotate
+     * embedders.
+     */
+    readonly embedderId?: string;
+    /**
+     * Optional tier tag to attach to indexed entries (`'hot'` /
+     * `'warm'` / `'cold'`). Useful when read-side `defineRAG` should
+     * filter to a subset of the corpus.
+     */
+    readonly tier?: 'hot' | 'warm' | 'cold';
+    /**
+     * Optional TTL in milliseconds from indexing time. Useful for
+     * compliance retention windows (e.g., re-index quarterly).
+     */
+    readonly ttlMs?: number;
+    /**
+     * Optional abort signal — embedders making network calls thread
+     * this through to abort batch indexing on shutdown / timeout.
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Embed + persist documents. Returns the count actually indexed
+ * (skips duplicates if the store rejects them). Throws on embedder
+ * failure or store error — fail loud at startup is desirable.
+ */
+export declare function indexDocuments(store: MemoryStore, embedder: Embedder, documents: readonly RagDocument[], options?: IndexDocumentsOptions): Promise<number>;
+//# sourceMappingURL=indexDocuments.d.ts.map

package/dist/types/lib/rag/indexDocuments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexDocuments.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/indexDocuments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAID;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAwCjB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",