network-ai 5.14.0 → 5.15.0

package/dist/esm/lib/context-composer.js

@@ -0,0 +1,332 @@
+"use strict";
+/**
+ * Context Composer — token-budgeted, relevance-ranked context assembly.
+ *
+ * Agents have large context windows but a much smaller *effective reasoning*
+ * window: irrelevant, stale, or noisy context degrades output quality long
+ * before the hard token limit ("context rot"). This module assembles the
+ * context block for an LLM call from candidate sources (blackboard entries,
+ * project context, memory recall) under a **hard token budget**, ranked by:
+ *
+ *   score = w.relevance × relevance + w.recency × recency + w.affinity × affinity
+ *
+ * - **relevance** — semantic similarity to the task via a pluggable
+ *   {@link SemanticRanker} (BYOE — e.g. wrap `SemanticMemory`), with a
+ *   deterministic lexical-overlap fallback when no ranker is supplied;
+ * - **recency**  — exponential half-life decay on the entry timestamp
+ *   (the same math `EpisodicMemory` uses);
+ * - **affinity** — scope-tag match on the key (same substring semantics as
+ *   `ContextThrottler`).
+ *
+ * Pinned sources (task-critical instructions, Layer-3 project context) are
+ * always included first. Assembly is position-aware by default: the
+ * strongest items are placed at the start *and end* of the block, weakest in
+ * the middle — mitigating "lost in the middle" attention decay.
+ *
+ * The result carries full observability metadata: what was included,
+ * what was excluded and why, token usage, and budget utilization.
+ *
+ * @example
+ * ```ts
+ * const composer = new ContextComposer();
+ * const sources = ContextComposer.fromSnapshot(blackboard.getScopedSnapshot('analyst'));
+ * const pack = await composer.compose(sources, {
+ *   task: 'Summarize Q3 revenue anomalies',
+ *   budgetTokens: 2000,
+ *   scopeTags: ['analytics', 'task'],
+ * });
+ * llmPrompt = `${instructions}\n\n${pack.text}`;
+ * ```
+ *
+ * @module ContextComposer
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextComposer = void 0;
+exports.estimateTokens = estimateTokens;
+exports.createSemanticMemoryRanker = createSemanticMemoryRanker;
+// ============================================================================
+// TOKEN ESTIMATION
+// ============================================================================
+/**
+ * Estimate the token count of a text without a tokenizer dependency.
+ *
+ * Uses the ~4-characters-per-token heuristic blended with a word count
+ * (English prose averages ~0.75 tokens/word; code and JSON run denser).
+ * Accurate to roughly ±15% across prose/code/JSON — sufficient for budget
+ * enforcement, not for billing.
+ */
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    const byChars = text.length / 4;
+    const words = text.split(/\s+/).filter(Boolean).length;
+    const byWords = words * 1.33;
+    return Math.max(1, Math.ceil((byChars + byWords) / 2));
+}
+// ============================================================================
+// INTERNAL HELPERS
+// ============================================================================
+/** Tokenize text into a lowercase word set for lexical overlap scoring. */
+function wordSet(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/)
+        .filter((w) => w.length > 2));
+}
+/**
+ * Deterministic lexical relevance: fraction of task words present in the
+ * item (key + text). Zero-dependency fallback when no semantic ranker is
+ * configured.
+ */
+function lexicalRelevance(taskWords, item) {
+    if (taskWords.size === 0)
+        return 0;
+    const itemWords = wordSet(`${item.key} ${item.text}`);
+    if (itemWords.size === 0)
+        return 0;
+    let hits = 0;
+    for (const w of taskWords) {
+        if (itemWords.has(w))
+            hits++;
+    }
+    return hits / taskWords.size;
+}
+/** Exponential half-life recency decay (1 = now, → 0 with age). */
+function recencyScore(timestamp, halfLifeMs, now) {
+    if (!timestamp)
+        return 0.5; // unknown age — neutral
+    const t = Date.parse(timestamp);
+    if (Number.isNaN(t))
+        return 0.5;
+    const elapsed = Math.max(0, now - t);
+    return Math.pow(0.5, elapsed / halfLifeMs);
+}
+/** Scope-tag affinity — ContextThrottler substring semantics on the key. */
+function affinityScore(key, scopeTags) {
+    if (!scopeTags || scopeTags.length === 0)
+        return 0.5; // no scoping — neutral
+    const lowerKey = key.toLowerCase();
+    return scopeTags.some((tag) => lowerKey.includes(tag.toLowerCase())) ? 1 : 0;
+}
+/** True when the entry's TTL has already elapsed relative to its timestamp. */
+function isStale(source, now) {
+    if (source.ttl === null || source.ttl === undefined)
+        return false;
+    if (!source.timestamp)
+        return false;
+    const t = Date.parse(source.timestamp);
+    if (Number.isNaN(t))
+        return false;
+    return now - t > source.ttl * 1000;
+}
+/** Render one item as a labelled context block. */
+function renderBlock(item) {
+    const origin = item.sourceAgent ? ` (from ${item.sourceAgent})` : '';
+    return `### ${item.key}${origin}\n${item.text}`;
+}
+/**
+ * Serpentine layout: ranked items `[1,2,3,4,5]` become `[1,3,5,4,2]` —
+ * strongest first, second-strongest last, weakest in the middle.
+ */
+function positionAwareLayout(ranked) {
+    const head = [];
+    const tail = [];
+    ranked.forEach((item, i) => {
+        if (i % 2 === 0)
+            head.push(item);
+        else
+            tail.unshift(item);
+    });
+    return [...head, ...tail];
+}
+/**
+ * Adapt a `SemanticMemory` instance (or anything with a compatible
+ * `search()`) into a {@link SemanticRanker}. Items the memory does not know
+ * about simply fall back to lexical scoring.
+ */
+function createSemanticMemoryRanker(memory) {
+    return async (query, items) => {
+        const results = await memory.search(query, items.length, 0);
+        const scores = new Map();
+        for (const r of results) {
+            // Cosine similarity may be negative — clamp to 0–1.
+            scores.set(r.key, Math.max(0, Math.min(1, r.score)));
+        }
+        return scores;
+    };
+}
+// ============================================================================
+// CONTEXT COMPOSER
+// ============================================================================
+/**
+ * Assembles token-budgeted, relevance-ranked context packs from candidate
+ * sources. See the module docs for the ranking model.
+ */
+class ContextComposer {
+    halfLifeMs;
+    weights;
+    ranker;
+    constructor(options = {}) {
+        this.halfLifeMs = options.halfLifeMs ?? 1_800_000;
+        if (this.halfLifeMs <= 0) {
+            throw new Error('ContextComposer: halfLifeMs must be > 0');
+        }
+        const w = { relevance: 0.5, recency: 0.3, affinity: 0.2, ...(options.weights ?? {}) };
+        const sum = w.relevance + w.recency + w.affinity;
+        if (sum <= 0) {
+            throw new Error('ContextComposer: score weights must sum to a positive number');
+        }
+        this.weights = {
+            relevance: w.relevance / sum,
+            recency: w.recency / sum,
+            affinity: w.affinity / sum,
+        };
+        this.ranker = options.ranker;
+    }
+    /**
+     * Convert a blackboard snapshot (`getSnapshot()` / `getScopedSnapshot()`
+     * shape) into {@link ContextSource} candidates. Values are rendered as
+     * strings (JSON for objects) and truncated to `maxValueChars`.
+     */
+    static fromSnapshot(snapshot, options = {}) {
+        const maxChars = options.maxValueChars ?? 4000;
+        const sources = [];
+        for (const [key, raw] of Object.entries(snapshot ?? {})) {
+            if (raw === null || raw === undefined)
+                continue;
+            let text;
+            let sourceAgent;
+            let timestamp;
+            let ttl;
+            if (typeof raw === 'object' && ('value' in raw)) {
+                const entry = raw;
+                const v = entry.value;
+                text = typeof v === 'string' ? v : JSON.stringify(v);
+                sourceAgent = entry.sourceAgent ?? entry.source_agent;
+                timestamp = entry.timestamp;
+                ttl = entry.ttl;
+            }
+            else {
+                text = typeof raw === 'string' ? raw : JSON.stringify(raw);
+            }
+            if (text === undefined || text === null)
+                continue;
+            sources.push({
+                key,
+                text: text.length > maxChars ? `${text.slice(0, maxChars)}…[truncated]` : text,
+                ...(sourceAgent !== undefined ? { sourceAgent } : {}),
+                ...(timestamp !== undefined ? { timestamp } : {}),
+                ...(ttl !== undefined ? { ttl } : {}),
+            });
+        }
+        return sources;
+    }
+    /**
+     * Rank the candidate sources against the task and assemble the largest
+     * high-signal context block that fits the token budget.
+     */
+    async compose(sources, options) {
+        if (!options || typeof options.task !== 'string' || options.task.trim() === '') {
+            throw new Error('ContextComposer.compose: options.task must be a non-empty string');
+        }
+        if (typeof options.budgetTokens !== 'number' || options.budgetTokens <= 0) {
+            throw new Error('ContextComposer.compose: options.budgetTokens must be > 0');
+        }
+        const now = Date.now();
+        const halfLifeMs = options.halfLifeMs ?? this.halfLifeMs;
+        const minScore = options.minScore ?? 0.05;
+        const maxItems = options.maxItems ?? 0;
+        const w = (() => {
+            if (!options.weights)
+                return this.weights;
+            const merged = { ...this.weights, ...options.weights };
+            const sum = merged.relevance + merged.recency + merged.affinity;
+            return sum > 0
+                ? { relevance: merged.relevance / sum, recency: merged.recency / sum, affinity: merged.affinity / sum }
+                : this.weights;
+        })();
+        const excluded = [];
+        const pinned = [];
+        const candidates = [];
+        for (const source of sources ?? []) {
+            if (!source || typeof source.key !== 'string' || source.key === '')
+                continue;
+            if (!source.text || source.text.trim() === '') {
+                excluded.push({ key: source.key ?? '(unknown)', reason: 'empty' });
+                continue;
+            }
+            if (isStale(source, now)) {
+                excluded.push({ key: source.key, reason: 'stale' });
+                continue;
+            }
+            (source.pinned ? pinned : candidates).push(source);
+        }
+        // ── Relevance scores (semantic ranker with lexical fallback) ────────────
+        const taskWords = wordSet(options.task);
+        let semanticScores = new Map();
+        const ranker = options.ranker ?? this.ranker;
+        if (ranker && candidates.length > 0) {
+            try {
+                semanticScores = await ranker(options.task, candidates.map((c) => ({ key: c.key, text: c.text })));
+            }
+            catch {
+                semanticScores = new Map(); // ranker failure → lexical fallback for all
+            }
+        }
+        // ── Score every candidate ────────────────────────────────────────────────
+        const ranked = candidates.map((c) => {
+            const relevance = semanticScores.get(c.key) ?? lexicalRelevance(taskWords, c);
+            const recency = recencyScore(c.timestamp, halfLifeMs, now);
+            const affinity = affinityScore(c.key, options.scopeTags);
+            const score = w.relevance * relevance + w.recency * recency + w.affinity * affinity;
+            return { ...c, relevance, recency, affinity, score, tokens: estimateTokens(renderBlock(c)) };
+        });
+        ranked.sort((a, b) => b.score - a.score);
+        // ── Budget-enforced selection: pinned first, then by score ──────────────
+        const included = [];
+        let usedTokens = 0;
+        for (const p of pinned) {
+            const tokens = estimateTokens(renderBlock(p));
+            if (usedTokens + tokens > options.budgetTokens) {
+                excluded.push({ key: p.key, reason: 'budget' });
+                continue;
+            }
+            usedTokens += tokens;
+            included.push({ ...p, relevance: 1, recency: 1, affinity: 1, score: 1, tokens });
+        }
+        for (const item of ranked) {
+            if (item.score < minScore) {
+                excluded.push({ key: item.key, reason: 'score', score: item.score });
+                continue;
+            }
+            if (maxItems > 0 && included.length >= maxItems) {
+                excluded.push({ key: item.key, reason: 'budget', score: item.score });
+                continue;
+            }
+            if (usedTokens + item.tokens > options.budgetTokens) {
+                excluded.push({ key: item.key, reason: 'budget', score: item.score });
+                continue;
+            }
+            usedTokens += item.tokens;
+            included.push(item);
+        }
+        // ── Assembly (pinned lead; ranked items in position-aware layout) ────────
+        const pinnedBlocks = included.filter((i) => i.pinned);
+        const rankedBlocks = included.filter((i) => !i.pinned);
+        const layout = (options.positionAware ?? true)
+            ? positionAwareLayout(rankedBlocks)
+            : rankedBlocks;
+        const text = [...pinnedBlocks, ...layout].map((i) => renderBlock(i)).join('\n\n');
+        return {
+            text,
+            included,
+            excluded,
+            budgetTokens: options.budgetTokens,
+            usedTokens,
+            utilization: Math.min(1, usedTokens / options.budgetTokens),
+        };
+    }
+}
+exports.ContextComposer = ContextComposer;
+//# sourceMappingURL=context-composer.js.map

package/dist/esm/lib/context-composer.js.map

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

package/dist/esm/lib/mcp-tools-context.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * MCP Context Tools — signal-over-noise retrieval for MCP agents.
+ *
+ * Two tools that let any MCP client (Claude Code, Codex, Gemini CLI, Cursor)
+ * pull *curated* shared state instead of dumping the whole blackboard into
+ * its own context window:
+ *
+ *   - `context_pack`      — "give me everything relevant to task X in
+ *     ≤ N tokens": a token-budgeted, relevance-ranked, position-aware
+ *     context brief assembled by {@link ContextComposer} from the agent's
+ *     scoped blackboard snapshot.
+ *   - `blackboard_search` — ranked top-K search over blackboard entries.
+ *     Uses a semantic ranker when one is wired (BYOE `SemanticMemory`),
+ *     falling back to deterministic lexical overlap scoring otherwise —
+ *     always works out of the box.
+ *
+ * Implements the same `McpToolProvider` contract as the other tool modules,
+ * so it registers directly on `McpCombinedBridge`.
+ *
+ * @example
+ * ```typescript
+ * const contextTools = new ContextMcpTools({ blackboard });
+ * combined.register(contextTools);
+ * // MCP client:  context_pack { task: "fix the parser bug", budget_tokens: 1500, agent_id: "claude-code" }
+ * ```
+ *
+ * @module mcp-tools-context
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextMcpTools = exports.CONTEXT_TOOL_DEFINITIONS = void 0;
+const context_composer_1 = require("./context-composer");
+// ============================================================================
+// TOOL DEFINITIONS
+// ============================================================================
+/** MCP tool definitions for the two context tools. */
+exports.CONTEXT_TOOL_DEFINITIONS = [
+    {
+        name: 'context_pack',
+        description: 'Assemble a token-budgeted, relevance-ranked context brief from the shared blackboard for a given task. ' +
+            'Use this INSTEAD of blackboard_list + many blackboard_read calls: it returns only the entries most relevant ' +
+            'to your task, ranked by semantic/lexical relevance, recency (half-life decay), and namespace affinity, ' +
+            'assembled position-aware (strongest items first and last) under a hard token budget. ' +
+            'Read-only — never modifies the blackboard. Returns {ok:true, text, used_tokens, budget_tokens, utilization, ' +
+            'included:[{key,score,tokens}], excluded:[{key,reason}]}. The `text` field is ready to use as working context. ' +
+            'Entries past their TTL are excluded automatically.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: 'The task or question driving relevance ranking (e.g. "diagnose the failing payment webhook")',
+                },
+                agent_id: {
+                    type: 'string',
+                    description: 'The agent requesting the pack (used for scoped access checks and audit)',
+                },
+                budget_tokens: {
+                    type: 'number',
+                    description: 'Hard token budget for the returned context text (default 2000)',
+                },
+                scope_tags: {
+                    type: 'string',
+                    description: 'Optional comma-separated scope tags for namespace affinity (e.g. "task,analytics")',
+                },
+                max_items: {
+                    type: 'number',
+                    description: 'Optional hard cap on the number of included entries (0 = unlimited)',
+                },
+            },
+            required: ['task', 'agent_id'],
+        },
+    },
+    {
+        name: 'blackboard_search',
+        description: 'Search the shared blackboard for entries relevant to a query and return the top-K ranked matches. ' +
+            'Use this instead of blackboard_list when you need *relevant* keys rather than *all* keys — it keeps noise ' +
+            'out of your context window. Read-only. Ranks semantically when the server has an embedding provider wired, ' +
+            'otherwise by deterministic lexical overlap (response includes which mode was used). ' +
+            'Returns {ok:true, mode, results:[{key, score, snippet, sourceAgent}], count}. ' +
+            'Follow up with blackboard_read for the full value of a specific key.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Natural-language search query (e.g. "budget decisions for Q3")',
+                },
+                agent_id: {
+                    type: 'string',
+                    description: 'The agent performing the search (used for scoped access checks)',
+                },
+                top_k: {
+                    type: 'number',
+                    description: 'Maximum number of results to return (default 5, max 50)',
+                },
+                min_score: {
+                    type: 'number',
+                    description: 'Minimum relevance score 0-1 (default 0)',
+                },
+            },
+            required: ['query', 'agent_id'],
+        },
+    },
+];
+// ============================================================================
+// CONTEXT MCP TOOLS
+// ============================================================================
+/**
+ * `McpToolProvider` exposing `context_pack` and `blackboard_search`.
+ * Register on a `McpCombinedBridge` alongside the other tool providers.
+ */
+class ContextMcpTools {
+    blackboard;
+    composer;
+    ranker;
+    semantic;
+    defaultBudgetTokens;
+    maxBudgetTokens;
+    constructor(options) {
+        if (!options || !options.blackboard) {
+            throw new Error('ContextMcpTools: options.blackboard is required');
+        }
+        this.blackboard = options.blackboard;
+        this.semantic = Boolean(options.memory);
+        this.ranker = options.memory ? (0, context_composer_1.createSemanticMemoryRanker)(options.memory) : undefined;
+        this.composer = options.composer
+            ?? new context_composer_1.ContextComposer(this.ranker ? { ranker: this.ranker } : {});
+        this.defaultBudgetTokens = options.defaultBudgetTokens ?? 2000;
+        this.maxBudgetTokens = options.maxBudgetTokens ?? 32_000;
+        if (this.defaultBudgetTokens <= 0 || this.maxBudgetTokens <= 0) {
+            throw new Error('ContextMcpTools: token budgets must be > 0');
+        }
+    }
+    /** Returns the MCP tool definitions provided by this module. */
+    getDefinitions() {
+        return exports.CONTEXT_TOOL_DEFINITIONS;
+    }
+    /**
+     * Dispatch a tool call by name. All errors are caught and returned as
+     * `{ ok: false, error }`.
+     */
+    async call(toolName, args) {
+        try {
+            switch (toolName) {
+                case 'context_pack': return await this._pack(args);
+                case 'blackboard_search': return await this._search(args);
+                default:
+                    return { ok: false, tool: toolName, error: `Unknown tool: "${toolName}"` };
+            }
+        }
+        catch (err) {
+            return {
+                ok: false,
+                tool: toolName,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Tool implementations
+    // --------------------------------------------------------------------------
+    async _pack(args) {
+        const task = this._requireString(args, 'task');
+        const agentId = this._requireString(args, 'agent_id');
+        const budget = this._clampNumber(args['budget_tokens'], this.defaultBudgetTokens, 1, this.maxBudgetTokens);
+        const maxItems = this._clampNumber(args['max_items'], 0, 0, 10_000);
+        const scopeTags = typeof args['scope_tags'] === 'string' && args['scope_tags'].trim() !== ''
+            ? args['scope_tags'].split(',').map((t) => t.trim()).filter(Boolean)
+            : undefined;
+        const sources = context_composer_1.ContextComposer.fromSnapshot(this._snapshot(agentId));
+        const pack = await this.composer.compose(sources, {
+            task,
+            budgetTokens: budget,
+            ...(scopeTags ? { scopeTags } : {}),
+            ...(maxItems > 0 ? { maxItems } : {}),
+        });
+        return {
+            ok: true,
+            tool: 'context_pack',
+            data: {
+                text: pack.text,
+                used_tokens: pack.usedTokens,
+                budget_tokens: pack.budgetTokens,
+                utilization: Number(pack.utilization.toFixed(3)),
+                mode: this.semantic ? 'semantic' : 'lexical',
+                included: pack.included.map((i) => ({
+                    key: i.key,
+                    score: Number(i.score.toFixed(3)),
+                    tokens: i.tokens,
+                })),
+                excluded: pack.excluded.map((e) => ({
+                    key: e.key,
+                    reason: e.reason,
+                    ...(e.score !== undefined ? { score: Number(e.score.toFixed(3)) } : {}),
+                })),
+            },
+        };
+    }
+    async _search(args) {
+        const query = this._requireString(args, 'query');
+        const agentId = this._requireString(args, 'agent_id');
+        const topK = this._clampNumber(args['top_k'], 5, 1, 50);
+        const minScore = this._clampNumber(args['min_score'], 0, 0, 1);
+        const sources = context_composer_1.ContextComposer.fromSnapshot(this._snapshot(agentId));
+        // Rank purely by relevance: reuse the composer with relevance-only
+        // weights and an unbounded budget, then take the top-K.
+        const ranked = await this.composer.compose(sources, {
+            task: query,
+            budgetTokens: this.maxBudgetTokens,
+            weights: { relevance: 1, recency: 0, affinity: 0 },
+            minScore: Math.max(minScore, 0.000_001), // drop zero-relevance items
+            positionAware: false,
+        });
+        const results = ranked.included
+            .slice(0, topK)
+            .map((i) => ({
+            key: i.key,
+            score: Number(i.relevance.toFixed(3)),
+            snippet: i.text.length > 240 ? `${i.text.slice(0, 240)}…` : i.text,
+            ...(i.sourceAgent ? { sourceAgent: i.sourceAgent } : {}),
+        }));
+        return {
+            ok: true,
+            tool: 'blackboard_search',
+            data: {
+                mode: this.semantic ? 'semantic' : 'lexical',
+                results,
+                count: results.length,
+                query_tokens: (0, context_composer_1.estimateTokens)(query),
+            },
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Helpers
+    // --------------------------------------------------------------------------
+    _snapshot(agentId) {
+        if (this.blackboard.getScopedSnapshot) {
+            return this.blackboard.getScopedSnapshot(agentId);
+        }
+        return this.blackboard.getSnapshot();
+    }
+    _requireString(args, field) {
+        const val = args[field];
+        if (typeof val !== 'string' || val.trim() === '') {
+            throw new Error(`Missing required field "${field}" (must be a non-empty string)`);
+        }
+        return val;
+    }
+    /** Accept number or numeric string; clamp into [min, max]; fall back to a default. */
+    _clampNumber(raw, fallback, min, max) {
+        let n;
+        if (typeof raw === 'number')
+            n = raw;
+        else if (typeof raw === 'string' && raw.trim() !== '')
+            n = Number(raw);
+        else
+            return fallback;
+        if (!Number.isFinite(n))
+            return fallback;
+        return Math.min(max, Math.max(min, Math.floor(n)));
+    }
+}
+exports.ContextMcpTools = ContextMcpTools;
+//# sourceMappingURL=mcp-tools-context.js.map

package/dist/esm/lib/mcp-tools-context.js.map

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

package/dist/index.d.ts

@@ -218,6 +218,10 @@ export { createElicitationApprovalCallback, StdioElicitationChannel } from './li
 export type { ElicitationCreateParams, ElicitationResult, ElicitationRequestSender, ElicitationRequestedSchema, ElicitationSchemaProperty, ElicitationApprovalOptions } from './lib/mcp-elicitation';
 export { A2AServer } from './lib/a2a-server';
 export type { A2AServerOptions, A2AServerTask, A2AServerTaskState, A2ATaskExecutor } from './lib/a2a-server';
+export { ContextComposer, estimateTokens, createSemanticMemoryRanker } from './lib/context-composer';
+export type { ContextSource, RankedContextItem, ComposedContext, ComposeOptions, ContextComposerOptions, ScoreWeights, SemanticRanker, SemanticSearchLike, ExclusionReason, ExcludedItem } from './lib/context-composer';
+export { ContextMcpTools, CONTEXT_TOOL_DEFINITIONS } from './lib/mcp-tools-context';
+export type { ContextMcpToolsOptions } from './lib/mcp-tools-context';
 export { createAdapterTestSuite } from './lib/adapter-test-harness';
 export type { AdapterTestSuiteConfig, AdapterTestResult, AssertFn, SectionFn } from './lib/adapter-test-harness';
 export { SwarmTransportServer, SwarmTransportClient } from './lib/swarm-transport';