@framers/agentos 0.1.29 → 0.1.30

package/dist/discovery/CapabilityDiscoveryEngine.js

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview Capability Discovery Engine — main orchestrator.
+ * @module @framers/agentos/discovery/CapabilityDiscoveryEngine
+ *
+ * Coordinates the capability index, relationship graph, and context assembler
+ * to provide tiered, semantic capability discovery for AgentOS agents.
+ *
+ * Architecture:
+ *   User Message → CapabilityIndex.search() → CapabilityGraph.rerank()
+ *                → CapabilityContextAssembler.assemble() → CapabilityDiscoveryResult
+ *
+ * Performance targets:
+ *   - Initialize: ~3s (one-time embedding generation for ~100 capabilities)
+ *   - Per-turn discover(): ~50ms cold (embedding) / ~5ms warm (cache hit)
+ *   - Context tokens: ~1,850 (down from ~20,000 with static dumps)
+ */
+import { DEFAULT_DISCOVERY_CONFIG } from './types.js';
+import { CapabilityIndex } from './CapabilityIndex.js';
+import { CapabilityGraph } from './CapabilityGraph.js';
+import { CapabilityContextAssembler } from './CapabilityContextAssembler.js';
+// ============================================================================
+// CAPABILITY DISCOVERY ENGINE
+// ============================================================================
+export class CapabilityDiscoveryEngine {
+    constructor(embeddingManager, vectorStore, config) {
+        this.indexVersion = 0;
+        this.initialized = false;
+        this.config = { ...DEFAULT_DISCOVERY_CONFIG, ...config };
+        this.index = new CapabilityIndex(embeddingManager, vectorStore, this.config.collectionName, this.config.embeddingModelId);
+        this.graph = new CapabilityGraph();
+        this.assembler = new CapabilityContextAssembler(this.index.getEmbeddingStrategy());
+    }
+    // ============================================================================
+    // INITIALIZATION
+    // ============================================================================
+    /**
+     * Initialize the engine: build index + graph from all capability sources.
+     *
+     * @param sources - Tools, skills, extensions, channels, and manifest entries
+     * @param presetCoOccurrences - Co-occurrence data from agent presets
+     */
+    async initialize(sources, presetCoOccurrences) {
+        // 1. Build the vector index (normalizes sources + embeds + stores)
+        await this.index.buildIndex(sources);
+        // 2. Build the relationship graph
+        const allCapabilities = this.index.getAllCapabilities();
+        this.graph.buildGraph(allCapabilities, presetCoOccurrences);
+        this.indexVersion++;
+        this.initialized = true;
+    }
+    // ============================================================================
+    // DISCOVERY
+    // ============================================================================
+    /**
+     * Discover capabilities relevant to a user message.
+     *
+     * Flow:
+     * 1. Semantic search against capability embeddings
+     * 2. Graph-based re-ranking (boost related capabilities)
+     * 3. Token-budgeted tiered assembly
+     *
+     * Returns a CapabilityDiscoveryResult with Tier 0/1/2 context.
+     */
+    async discover(userMessage, options) {
+        if (!this.initialized) {
+            return this.emptyResult();
+        }
+        const queryConfig = { ...this.config, ...options?.config };
+        const embeddingStart = performance.now();
+        // 1. Semantic search
+        // Retrieve more candidates than needed for graph re-ranking to work effectively
+        const searchTopK = queryConfig.tier1TopK * 2;
+        const searchResults = await this.index.search(userMessage, searchTopK, {
+            kind: options?.kind,
+            category: options?.category,
+            onlyAvailable: options?.onlyAvailable,
+        });
+        const embeddingTimeMs = performance.now() - embeddingStart;
+        // 2. Graph-based re-ranking
+        let finalResults = searchResults;
+        let graphTraversalTimeMs = 0;
+        if (queryConfig.useGraphReranking && searchResults.length > 0) {
+            const graphStart = performance.now();
+            const reranked = this.graph.rerank(searchResults.map((r) => ({ id: r.descriptor.id, score: r.score })), queryConfig.graphBoostFactor);
+            // Map back to CapabilitySearchResult format
+            finalResults = reranked
+                .map((r) => {
+                const descriptor = this.index.getCapability(r.id);
+                if (!descriptor)
+                    return null;
+                return { descriptor, score: r.score };
+            })
+                .filter((r) => r !== null);
+            graphTraversalTimeMs = performance.now() - graphStart;
+        }
+        // 3. Build Tier 0 category summary
+        const tier0 = this.assembler.buildTier0(this.index.getAllCapabilities(), this.indexVersion);
+        // 4. Assemble tiered result with token budgets
+        return this.assembler.assemble(tier0, finalResults, queryConfig, {
+            embeddingTimeMs,
+            graphTraversalTimeMs,
+        });
+    }
+    // ============================================================================
+    // DETAIL ACCESS
+    // ============================================================================
+    /**
+     * Get full detail for a specific capability by ID.
+     */
+    getCapabilityDetail(id) {
+        return this.index.getCapability(id);
+    }
+    // ============================================================================
+    // INDEX MANAGEMENT
+    // ============================================================================
+    /**
+     * Refresh the index incrementally.
+     * Called when manifest files change or new capabilities are added at runtime.
+     */
+    async refreshIndex(sources) {
+        if (!sources)
+            return;
+        // Normalize and upsert new sources
+        const fullSources = {
+            tools: sources.tools,
+            skills: sources.skills,
+            extensions: sources.extensions,
+            channels: sources.channels,
+            manifests: sources.manifests,
+        };
+        const newDescriptors = this.index.normalizeSources(fullSources);
+        for (const desc of newDescriptors) {
+            await this.index.upsertCapability(desc);
+        }
+        // Rebuild graph with all capabilities
+        const allCapabilities = this.index.getAllCapabilities();
+        this.graph.buildGraph(allCapabilities);
+        this.indexVersion++;
+        this.assembler.invalidateCache();
+    }
+    // ============================================================================
+    // ACCESSORS
+    // ============================================================================
+    isInitialized() {
+        return this.initialized;
+    }
+    listCapabilityIds() {
+        return this.index.listIds();
+    }
+    /**
+     * Get the current configuration.
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Get index statistics.
+     */
+    getStats() {
+        return {
+            capabilityCount: this.index.size(),
+            graphNodes: this.graph.nodeCount(),
+            graphEdges: this.graph.edgeCount(),
+            indexVersion: this.indexVersion,
+        };
+    }
+    /**
+     * Render a discovery result into a string suitable for prompt injection.
+     */
+    renderForPrompt(result) {
+        return this.assembler.renderForPrompt(result);
+    }
+    // ============================================================================
+    // INTERNAL
+    // ============================================================================
+    emptyResult() {
+        return {
+            tier0: 'No capabilities indexed. Discovery engine not initialized.',
+            tier1: [],
+            tier2: [],
+            tokenEstimate: {
+                tier0Tokens: 10,
+                tier1Tokens: 0,
+                tier2Tokens: 0,
+                totalTokens: 10,
+            },
+            diagnostics: {
+                queryTimeMs: 0,
+                embeddingTimeMs: 0,
+                graphTraversalTimeMs: 0,
+                candidatesScanned: 0,
+                capabilitiesRetrieved: 0,
+            },
+        };
+    }
+}
+//# sourceMappingURL=CapabilityDiscoveryEngine.js.map

package/dist/discovery/CapabilityDiscoveryEngine.js.map

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

package/dist/discovery/CapabilityEmbeddingStrategy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Capability Embedding Strategy
+ * @module @framers/agentos/discovery/CapabilityEmbeddingStrategy
+ *
+ * Constructs the embedding text for each capability descriptor.
+ * The strategy captures WHEN a capability is useful (intent-oriented),
+ * not just what it does (description-only).
+ *
+ * Design informed by:
+ * - ToolLLM Neural API Retriever: embedding API docs (name, description, params)
+ *   achieves NDCG@5 of 84.9 on 16K+ APIs
+ * - MCP-RAG: decomposing tools into parameter-level embeddings improves matching
+ * - Context Rot (Chroma 2025): keeping embedded text concise maximizes retrieval precision
+ */
+import type { CapabilityDescriptor } from './types.js';
+/**
+ * Builds optimized embedding text for capability descriptors.
+ *
+ * The embedding text is structured to maximize semantic match with user intents:
+ * 1. Name/display name — captures exact-match queries
+ * 2. Description — core semantic content
+ * 3. Category + tags — captures categorical queries ("communication tool")
+ * 4. Parameter names — captures action queries ("I need to search for X")
+ * 5. Dependencies — captures composition queries ("tool that works with GitHub")
+ */
+export declare class CapabilityEmbeddingStrategy {
+    /**
+     * Build the text that will be embedded for a capability.
+     * Designed to be concise (typically 100-300 tokens) while capturing
+     * the key semantic signals for retrieval.
+     */
+    buildEmbeddingText(cap: CapabilityDescriptor): string;
+    /**
+     * Build a compact summary text for Tier 1 display.
+     * This is shown to the LLM when a capability is retrieved as relevant.
+     * Kept to ~30-50 tokens per capability.
+     */
+    buildCompactSummary(cap: CapabilityDescriptor): string;
+    /**
+     * Build the full detail text for Tier 2 injection.
+     * Includes full schema and/or SKILL.md content.
+     */
+    buildFullDetailText(cap: CapabilityDescriptor): string;
+}
+//# sourceMappingURL=CapabilityEmbeddingStrategy.d.ts.map

package/dist/discovery/CapabilityEmbeddingStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityEmbeddingStrategy.d.ts","sourceRoot":"","sources":["../../src/discovery/CapabilityEmbeddingStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAMvD;;;;;;;;;GASG;AACH,qBAAa,2BAA2B;IACtC;;;;OAIG;IACH,kBAAkB,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM;IA0CrD;;;;OAIG;IACH,mBAAmB,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM;IAiCtD;;;OAGG;IACH,mBAAmB,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM;CAkCvD"}

package/dist/discovery/CapabilityEmbeddingStrategy.js

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Capability Embedding Strategy
+ * @module @framers/agentos/discovery/CapabilityEmbeddingStrategy
+ *
+ * Constructs the embedding text for each capability descriptor.
+ * The strategy captures WHEN a capability is useful (intent-oriented),
+ * not just what it does (description-only).
+ *
+ * Design informed by:
+ * - ToolLLM Neural API Retriever: embedding API docs (name, description, params)
+ *   achieves NDCG@5 of 84.9 on 16K+ APIs
+ * - MCP-RAG: decomposing tools into parameter-level embeddings improves matching
+ * - Context Rot (Chroma 2025): keeping embedded text concise maximizes retrieval precision
+ */
+// ============================================================================
+// EMBEDDING STRATEGY
+// ============================================================================
+/**
+ * Builds optimized embedding text for capability descriptors.
+ *
+ * The embedding text is structured to maximize semantic match with user intents:
+ * 1. Name/display name — captures exact-match queries
+ * 2. Description — core semantic content
+ * 3. Category + tags — captures categorical queries ("communication tool")
+ * 4. Parameter names — captures action queries ("I need to search for X")
+ * 5. Dependencies — captures composition queries ("tool that works with GitHub")
+ */
+export class CapabilityEmbeddingStrategy {
+    /**
+     * Build the text that will be embedded for a capability.
+     * Designed to be concise (typically 100-300 tokens) while capturing
+     * the key semantic signals for retrieval.
+     */
+    buildEmbeddingText(cap) {
+        const parts = [];
+        // 1. Name and display name (captures exact-match queries)
+        if (cap.displayName !== cap.name) {
+            parts.push(`${cap.displayName} (${cap.name})`);
+        }
+        else {
+            parts.push(cap.name);
+        }
+        // 2. Description (core semantics — the most important part)
+        if (cap.description) {
+            parts.push(cap.description);
+        }
+        // 3. Category (captures categorical queries like "I need a developer tool")
+        if (cap.category) {
+            parts.push(`Category: ${cap.category}`);
+        }
+        // 4. Tags (captures use-case queries like "search", "automation", "messaging")
+        if (cap.tags.length > 0) {
+            parts.push(`Use cases: ${cap.tags.join(', ')}`);
+        }
+        // 5. For tools: extract parameter names from schema
+        //    This captures queries like "I need to specify a URL" → matches url param
+        if (cap.kind === 'tool' && cap.fullSchema) {
+            const paramNames = extractParameterNames(cap.fullSchema);
+            if (paramNames.length > 0) {
+                parts.push(`Parameters: ${paramNames.join(', ')}`);
+            }
+        }
+        // 6. Dependencies (captures composition queries)
+        if (cap.requiredTools.length > 0) {
+            parts.push(`Requires: ${cap.requiredTools.join(', ')}`);
+        }
+        return parts.join('\n');
+    }
+    /**
+     * Build a compact summary text for Tier 1 display.
+     * This is shown to the LLM when a capability is retrieved as relevant.
+     * Kept to ~30-50 tokens per capability.
+     */
+    buildCompactSummary(cap) {
+        const parts = [];
+        // Name and kind
+        parts.push(`${cap.name} (${cap.kind})`);
+        // Truncated description
+        const desc = cap.description.length > 120
+            ? cap.description.slice(0, 117) + '...'
+            : cap.description;
+        parts.push(desc);
+        // Key params for tools (top 3)
+        if (cap.kind === 'tool' && cap.fullSchema) {
+            const params = extractParameterNames(cap.fullSchema, 3);
+            if (params.length > 0) {
+                parts.push(`Params: ${params.join(', ')}`);
+            }
+        }
+        // Dependencies
+        if (cap.requiredTools.length > 0) {
+            parts.push(`Requires: ${cap.requiredTools.join(', ')}`);
+        }
+        // Availability warning
+        if (!cap.available) {
+            parts.push('[not available — missing secrets or dependencies]');
+        }
+        return parts.join('. ');
+    }
+    /**
+     * Build the full detail text for Tier 2 injection.
+     * Includes full schema and/or SKILL.md content.
+     */
+    buildFullDetailText(cap) {
+        const parts = [];
+        parts.push(`# ${cap.displayName}`);
+        parts.push(`Kind: ${cap.kind} | Category: ${cap.category}`);
+        if (cap.description) {
+            parts.push(`\n${cap.description}`);
+        }
+        // Full schema for tools
+        if (cap.kind === 'tool' && cap.fullSchema) {
+            parts.push('\n## Input Schema');
+            parts.push(formatSchemaForContext(cap.fullSchema));
+        }
+        // Full SKILL.md content for skills
+        if (cap.fullContent) {
+            parts.push('\n## Skill Instructions');
+            parts.push(cap.fullContent);
+        }
+        // Required secrets
+        if (cap.requiredSecrets.length > 0) {
+            parts.push(`\nRequired secrets: ${cap.requiredSecrets.join(', ')}`);
+        }
+        // Tags
+        if (cap.tags.length > 0) {
+            parts.push(`Tags: ${cap.tags.join(', ')}`);
+        }
+        return parts.join('\n');
+    }
+}
+// ============================================================================
+// HELPERS
+// ============================================================================
+/**
+ * Extract property names from a JSON Schema object.
+ * Returns the top-level property names, optionally limited.
+ */
+function extractParameterNames(schema, limit) {
+    const properties = schema.properties;
+    if (!properties)
+        return [];
+    const names = Object.keys(properties);
+    return limit ? names.slice(0, limit) : names;
+}
+/**
+ * Format a JSON Schema for context injection.
+ * Produces a compact, human-readable representation.
+ */
+function formatSchemaForContext(schema) {
+    const properties = schema.properties;
+    if (!properties)
+        return '(no parameters)';
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const lines = [];
+    for (const [name, prop] of Object.entries(properties)) {
+        const type = prop.type ?? 'any';
+        const isRequired = required.has(name);
+        const desc = prop.description ? `: ${prop.description}` : '';
+        const enumValues = Array.isArray(prop.enum) ? ` [${prop.enum.join('|')}]` : '';
+        const defaultVal = prop.default !== undefined ? ` (default: ${JSON.stringify(prop.default)})` : '';
+        const reqLabel = isRequired ? ', required' : '';
+        lines.push(`  ${name} (${type}${reqLabel})${desc}${enumValues}${defaultVal}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=CapabilityEmbeddingStrategy.js.map

package/dist/discovery/CapabilityEmbeddingStrategy.js.map

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

package/dist/discovery/CapabilityGraph.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Capability Relationship Graph
+ * @module @framers/agentos/discovery/CapabilityGraph
+ *
+ * Lightweight, deterministic relationship graph over capabilities.
+ * Built from metadata (SKILL.md frontmatter, preset co-occurrence),
+ * NOT from LLM extraction.
+ *
+ * Uses graphology (already in codebase via GraphRAGEngine) for:
+ * - O(1) neighbor lookups
+ * - Edge attributes (type, weight)
+ * - Sub-millisecond traversal for ~100 nodes
+ *
+ * Implements ICapabilityGraph so Neo4j can be swapped in later
+ * if capabilities scale to 1000+.
+ *
+ * Edge types:
+ * - DEPENDS_ON: Skill → Tool (from requiredTools)
+ * - COMPOSED_WITH: Co-occur in agent presets (suggestedSkills + suggestedExtensions)
+ * - SAME_CATEGORY: Shared category (weak signal, low weight)
+ * - TAGGED_WITH: Shared tags (weighted by overlap count, ≥2 tags)
+ */
+import type { CapabilityDescriptor, CapabilityEdge, ICapabilityGraph, PresetCoOccurrence, RelatedCapability } from './types.js';
+export declare class CapabilityGraph implements ICapabilityGraph {
+    private graph;
+    constructor();
+    /**
+     * Build the graph from capability descriptors and preset co-occurrence data.
+     *
+     * Construction order:
+     * 1. Add all capabilities as nodes
+     * 2. Add DEPENDS_ON edges (skill → tool dependencies)
+     * 3. Add COMPOSED_WITH edges (preset co-occurrence)
+     * 4. Add TAGGED_WITH edges (shared tags, ≥2 overlap)
+     * 5. Add SAME_CATEGORY edges (weak signal)
+     */
+    buildGraph(capabilities: CapabilityDescriptor[], presetCoOccurrences?: PresetCoOccurrence[]): void;
+    /**
+     * Get capabilities related to a given capability (1-hop neighbors).
+     * Returns neighbors with edge weights, sorted by weight descending.
+     */
+    getRelated(capabilityId: string): RelatedCapability[];
+    /**
+     * Get the subgraph for a set of capability IDs.
+     * Returns all nodes and edges within the induced subgraph.
+     */
+    getSubgraph(capabilityIds: string[]): {
+        nodes: string[];
+        edges: CapabilityEdge[];
+    };
+    /**
+     * Apply graph-based re-ranking boost to search results.
+     *
+     * For each result in the search results:
+     * 1. Look up its graph neighbors
+     * 2. If a neighbor is also in the results, boost both by graphBoostFactor * edge weight
+     * 3. If a neighbor is NOT in results but has a DEPENDS_ON edge, add it as a candidate
+     *
+     * Returns re-ranked results with potentially new candidates added.
+     */
+    rerank(searchResults: Array<{
+        id: string;
+        score: number;
+    }>, graphBoostFactor: number): Array<{
+        id: string;
+        score: number;
+        boosted: boolean;
+    }>;
+    nodeCount(): number;
+    edgeCount(): number;
+    clear(): void;
+    /**
+     * Safely add an edge, handling the case where it already exists.
+     * If the edge already exists, update to the higher weight.
+     */
+    private safeAddEdge;
+}
+//# sourceMappingURL=CapabilityGraph.d.ts.map

package/dist/discovery/CapabilityGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilityGraph.d.ts","sourceRoot":"","sources":["../../src/discovery/CapabilityGraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EAEd,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAMpB,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,OAAO,CAAC,KAAK,CAAQ;;IAUrB;;;;;;;;;OASG;IACH,UAAU,CACR,YAAY,EAAE,oBAAoB,EAAE,EACpC,mBAAmB,CAAC,EAAE,kBAAkB,EAAE,GACzC,IAAI;IA2FP;;;OAGG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAoBrD;;;OAGG;IACH,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG;QACpC,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,KAAK,EAAE,cAAc,EAAE,CAAC;KACzB;IA4BD;;;;;;;;;OASG;IACH,MAAM,CACJ,aAAa,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,EACnD,gBAAgB,EAAE,MAAM,GACvB,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAsCzD,SAAS,IAAI,MAAM;IAInB,SAAS,IAAI,MAAM;IAInB,KAAK,IAAI,IAAI;IAQb;;;OAGG;IACH,OAAO,CAAC,WAAW;CAiCpB"}