network-ai 5.14.0 → 5.15.0

package/dist/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/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/lib/mcp-tools-context.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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
+ */
+import type { MCPToolDefinition, BlackboardToolResult, IBlackboard } from './mcp-blackboard-tools';
+import { ContextComposer, type SemanticSearchLike } from './context-composer';
+/** Options for {@link ContextMcpTools}. */
+export interface ContextMcpToolsOptions {
+    /** The blackboard to compose/search over (required) */
+    blackboard: IBlackboard;
+    /**
+     * Optional BYOE semantic memory. When provided, `blackboard_search` and
+     * `context_pack` rank by embedding similarity; otherwise both fall back
+     * to deterministic lexical scoring.
+     */
+    memory?: SemanticSearchLike;
+    /** Optional pre-configured composer (default: `new ContextComposer()`) */
+    composer?: ContextComposer;
+    /** Default token budget for `context_pack` when the caller omits one (default 2000) */
+    defaultBudgetTokens?: number;
+    /** Hard ceiling on any requested budget (default 32000) */
+    maxBudgetTokens?: number;
+}
+/** MCP tool definitions for the two context tools. */
+export declare const CONTEXT_TOOL_DEFINITIONS: MCPToolDefinition[];
+/**
+ * `McpToolProvider` exposing `context_pack` and `blackboard_search`.
+ * Register on a `McpCombinedBridge` alongside the other tool providers.
+ */
+export declare class ContextMcpTools {
+    private readonly blackboard;
+    private readonly composer;
+    private readonly ranker;
+    private readonly semantic;
+    private readonly defaultBudgetTokens;
+    private readonly maxBudgetTokens;
+    constructor(options: ContextMcpToolsOptions);
+    /** Returns the MCP tool definitions provided by this module. */
+    getDefinitions(): MCPToolDefinition[];
+    /**
+     * Dispatch a tool call by name. All errors are caught and returned as
+     * `{ ok: false, error }`.
+     */
+    call(toolName: string, args: Record<string, unknown>): Promise<BlackboardToolResult>;
+    private _pack;
+    private _search;
+    private _snapshot;
+    private _requireString;
+    /** Accept number or numeric string; clamp into [min, max]; fall back to a default. */
+    private _clampNumber;
+}
+//# sourceMappingURL=mcp-tools-context.d.ts.map

package/dist/lib/mcp-tools-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools-context.d.ts","sourceRoot":"","sources":["../../lib/mcp-tools-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACnG,OAAO,EACL,eAAe,EAKf,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAM5B,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,UAAU,EAAE,WAAW,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,uFAAuF;IACvF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD,sDAAsD;AACtD,eAAO,MAAM,wBAAwB,EAAE,iBAAiB,EAsEvD,CAAC;AAMF;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,OAAO,EAAE,sBAAsB;IAgB3C,gEAAgE;IAChE,cAAc,IAAI,iBAAiB,EAAE;IAIrC;;;OAGG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC;YAqB5E,KAAK;YAwCL,OAAO;IA2CrB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,cAAc;IAQtB,sFAAsF;IACtF,OAAO,CAAC,YAAY;CAQrB"}