@tasksai/install 0.1.20 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tasksai/install",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Shared TasksAI MCP installer CLI",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "src/",
     "runtime/server.py",
+    "runtime/skill_matcher.py",
     "runtime/requirements.txt",
     "README.md"
   ],

package/runtime/server.py

@@ -29,6 +29,15 @@ import uuid
 from datetime import datetime
 from pathlib import Path
 
+# The runtime is installed as a pair of adjacent Python files and is also
+# loaded directly by path in focused tests, so make the sibling matcher
+# importable without requiring a package install.
+_RUNTIME_DIR = Path(__file__).resolve().parent
+if str(_RUNTIME_DIR) not in sys.path:
+    sys.path.insert(0, str(_RUNTIME_DIR))
+
+from skill_matcher import POLICY_VERSION, match_skills
+
 # Force UTF-8 stdout/stderr on Windows (default is CP1252 which breaks emoji)
 if sys.stdout and hasattr(sys.stdout, 'reconfigure'):
     sys.stdout.reconfigure(encoding='utf-8', errors='replace')
@@ -484,6 +493,9 @@ _skills_cache_err_until = 0.0
 _triggers_cache           = None
 _triggers_cache_ts        = 0.0
 _triggers_cache_err_until = 0.0
+_matcher_config_cache     = None
+_matcher_config_cache_ts  = 0.0
+_matcher_config_err_until = 0.0
 
 
 async def api_get(path):
@@ -541,6 +553,25 @@ async def report_activation_event(event_name, *, skill_id=None, file_format=None
         pass
 
 
+def fallback_vertical(product_id):
+    """Build local vertical metadata without an API request."""
+    product_id = str(product_id or "").strip().lower() or "tasksai"
+    known = _VERTICAL_FALLBACKS.get(product_id)
+    if known:
+        return dict(known)
+    safe_id = re.sub(r"[^a-z0-9]+", "", product_id) or "tasksai"
+    display_name = f"{safe_id.title()}TasksAI"
+    return {
+        "product_id": product_id,
+        "product_name": display_name,
+        "display_name": display_name,
+        "tool_prefix": f"{safe_id}tasksai",
+        "occupation": "professional",
+        "support_email": "hello@tasksai.com",
+        "domain": "tasksai.com",
+    }
+
+
 async def load_vertical():
     """Fetch vertical metadata from /v1/me without crossing product boundaries."""
     global _vertical
@@ -548,22 +579,7 @@ async def load_vertical():
         path = f"/v1/me?product_id={PRODUCT_ID}" if PRODUCT_ID else "/v1/me"
         _vertical = await api_get(path)
     except Exception:
-        product_id = PRODUCT_ID.strip().lower() or "tasksai"
-        known = _VERTICAL_FALLBACKS.get(product_id)
-        if known:
-            _vertical = dict(known)
-        else:
-            safe_id = re.sub(r"[^a-z0-9]+", "", product_id) or "tasksai"
-            display_name = f"{safe_id.title()}TasksAI"
-            _vertical = {
-                "product_id": product_id,
-                "product_name": display_name,
-                "display_name": display_name,
-                "tool_prefix": f"{safe_id}tasksai",
-                "occupation": "professional",
-                "support_email": "hello@tasksai.com",
-                "domain": "tasksai.com",
-            }
+        _vertical = fallback_vertical(PRODUCT_ID)
     return _vertical
 
 
@@ -603,9 +619,21 @@ async def get_skills():
     return _skills_cache
 
 
+def product_ids_match(left, right):
+    """Compare canonical and legacy TasksAI product IDs."""
+    aliases = {
+        "farmertasksai": "farmer",
+        "lawtasksai": "law",
+        "realtortasksai": "realtor",
+    }
+    left_id = aliases.get(str(left or "").strip().lower(), str(left or "").strip().lower())
+    right_id = aliases.get(str(right or "").strip().lower(), str(right or "").strip().lower())
+    return left_id == right_id
+
+
 async def get_triggers():
     """Return trigger phrases {skill_id: [phrase, ...]}. Fails silently."""
-    global _triggers_cache, _triggers_cache_ts, _triggers_cache_err_until
+    global _triggers_cache, _triggers_cache_ts, _triggers_cache_err_until, _matcher_config_cache
     now = time.monotonic()
     if _triggers_cache is not None and (now - _triggers_cache_ts) < CACHE_TTL:
         return _triggers_cache
@@ -613,10 +641,37 @@ async def get_triggers():
         return _triggers_cache if _triggers_cache is not None else {}
     try:
         raw = await api_get("/v1/skills/triggers")
-        _triggers_cache = {
-            sid: [p.lower() for p in v.get("triggers", [])]
-            for sid, v in raw.items()
-        }
+        if isinstance(raw, dict) and raw.get("policy_version"):
+            _matcher_config_cache = {
+                key: raw[key]
+                for key in (
+                    "policy_version", "product_id", "default_result_count",
+                    "maximum_result_count", "thresholds", "stop_words",
+                    "context_words", "abbreviations",
+                )
+                if key in raw
+            }
+        if isinstance(raw, dict) and isinstance(raw.get("skills"), dict):
+            trigger_records = raw["skills"]
+        elif (
+            isinstance(raw, dict)
+            and raw.get("policy_version")
+            and isinstance(raw.get("triggers"), dict)
+        ):
+            trigger_records = raw["triggers"]
+        else:
+            trigger_records = raw if isinstance(raw, dict) else {}
+        active_product = (_vertical or {}).get("product_id", PRODUCT_ID)
+        _triggers_cache = {}
+        for sid, value in trigger_records.items():
+            if isinstance(value, dict):
+                if value.get("product_id") and not product_ids_match(value["product_id"], active_product):
+                    continue
+                value = value.get("triggers", [])
+            if isinstance(value, str):
+                value = [value]
+            if isinstance(value, (list, tuple)):
+                _triggers_cache[str(sid)] = [str(phrase).lower() for phrase in value if str(phrase).strip()]
         _triggers_cache_ts = now
         _triggers_cache_err_until = 0.0
     except Exception:
@@ -626,13 +681,54 @@ async def get_triggers():
     return _triggers_cache
 
 
+async def get_matching_config():
+    """Return cached safe matching policy metadata for the active product."""
+    global _matcher_config_cache, _matcher_config_cache_ts, _matcher_config_err_until
+    now = time.monotonic()
+    if _matcher_config_cache is not None and (now - _matcher_config_cache_ts) < CACHE_TTL:
+        return _matcher_config_cache
+    if now < _matcher_config_err_until:
+        return _matcher_config_cache
+    try:
+        raw = await api_get("/v1/skills/matching-config")
+        active_product = (_vertical or {}).get("product_id", PRODUCT_ID)
+        if (
+            isinstance(raw, dict)
+            and raw.get("policy_version") == POLICY_VERSION
+            and product_ids_match(raw.get("product_id"), active_product)
+        ):
+            _matcher_config_cache = {
+                key: raw[key]
+                for key in (
+                    "policy_version", "product_id", "default_result_count",
+                    "maximum_result_count", "thresholds", "stop_words",
+                    "context_words", "abbreviations",
+                )
+                if key in raw
+            }
+            _matcher_config_cache_ts = now
+            _matcher_config_err_until = 0.0
+    except Exception:
+        _matcher_config_err_until = now + ERROR_COOLDOWN
+    return _matcher_config_cache
+
+
+async def load_discovery_snapshot():
+    """Refresh public discovery metadata before accepting user prompts."""
+    await asyncio.gather(get_skills(), get_triggers(), get_matching_config())
+
+
+def active_abbreviations(product_id):
+    """Return the already-loaded product abbreviation map without network I/O."""
+    if _abbrevs_db is not None:
+        return _abbrevs_db
+    return _ABBREVS_FALLBACK.get(product_id, _DEFAULT_ABBREVS)
+
+
 def expand_query(query, product_id):
     """Expand vertical-specific abbreviations before matching."""
     # Prefer DB-loaded abbreviations; fall back to hardcoded map
-    if _abbrevs_db is not None:
-        abbrevs = _abbrevs_db
-    else:
-        abbrevs = _ABBREVS_FALLBACK.get(product_id, _DEFAULT_ABBREVS)
+    abbrevs = active_abbreviations(product_id)
     if not abbrevs:
         return query
     words = query.lower().split()
@@ -640,29 +736,6 @@ def expand_query(query, product_id):
     return (query + " " + " ".join(expansions)).strip() if expansions else query
 
 
-def _word_in_text(word, text):
-    """True if `word` appears as a whole word in `text`."""
-    return bool(re.search(r'(?<!\w)' + re.escape(word) + r'(?!\w)', text))
-
-
-def score_skill(skill, query_lower, query_words, triggers):
-    """Three-tier scoring: trigger match (10) > name match (3) > description match (1)."""
-    skill_id  = skill.get("id", "")
-    name_text = skill.get("name", "").lower()
-    desc_text = skill.get("description", "").lower()
-    full_text = name_text + " " + desc_text
-    # Tier 1 — trigger phrase (whole-word, bidirectional)
-    for phrase in triggers.get(skill_id, []):
-        if _word_in_text(phrase, query_lower) or _word_in_text(query_lower, phrase):
-            return 10
-    # Tier 2 — keyword
-    return sum(
-        3 if _word_in_text(w, name_text) else 1
-        for w in query_words
-        if _word_in_text(w, full_text)
-    )
-
-
 def safe_filename_component(value, fallback="tasksai-output", max_length=90):
     """Return a conservative filename stem with no path separators."""
     text = str(value or "").strip()
@@ -1091,6 +1164,13 @@ def build_tools(prefix, product_name, occupation):
                     "query": {
                         "type": "string",
                         "description": f"{domain_adjective.title()} topic or task ({examples})"
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 10,
+                        "default": 3,
+                        "description": "Maximum recommendations to show; defaults to 3. Increase to show more."
                     }
                 },
                 "required": ["query"]
@@ -1241,6 +1321,7 @@ async def list_tools():
     if _vertical is None:
         await load_vertical()
         await load_abbreviations()
+        await load_discovery_snapshot()
         _rebuild_tools()
     return _tools
 
@@ -1261,10 +1342,16 @@ def _rebuild_tools():
 
 @server.call_tool()
 async def call_tool(name, arguments):
-    # Ensure vertical loaded on first tool call
+    global _vertical
+    # Standard startup loads all public discovery metadata before accepting
+    # requests. Preserve privacy if a host bypasses startup and calls search or
+    # categories directly: use only bundled identity and empty/local caches.
     if _vertical is None:
-        await load_vertical()
-        await load_abbreviations()
+        if name.endswith("_search") or name.endswith("_categories"):
+            _vertical = fallback_vertical(PRODUCT_ID)
+        else:
+            await load_vertical()
+            await load_abbreviations()
         _rebuild_tools()
 
     v          = _vertical or {}
@@ -1276,35 +1363,49 @@ async def call_tool(name, arguments):
     try:
         # ── Search ────────────────────────────────────────────────────────────
         if name == f"{prefix}_search":
-            skills, triggers = await get_skills(), await get_triggers()
-            query        = expand_query(arguments.get("query", ""), product_id)
-            query_lower  = query.lower()
-            STOP_WORDS   = {"a","an","the","and","or","of","in","to","for","is","are",
-                            "with","at","by","on","from","as","it","its","be","was","can"}
-            raw_words    = query.split()
-            query_words  = [
-                w_lower for w_orig, w_lower in zip(raw_words, query_lower.split())
-                if w_lower not in STOP_WORDS and (len(w_lower) > 2 or w_orig.isupper())
-            ]
-            scored = [(score_skill(s, query_lower, query_words, triggers), s) for s in skills]
-            scored = [(sc, s) for sc, s in scored if sc > 0]
-            scored.sort(key=lambda x: -x[0])
-            matches = [s for _, s in scored[:5]]
+            # Discovery is snapshot-only. A user's raw prompt never causes a
+            # metadata refresh, API request, log entry, or telemetry event.
+            skills = _skills_cache if _skills_cache is not None else []
+            triggers = _triggers_cache if _triggers_cache is not None else {}
+            match = match_skills(
+                arguments.get("query", ""),
+                skills,
+                triggers,
+                product_id,
+                abbreviations=active_abbreviations(product_id),
+                config=_matcher_config_cache,
+                result_count=arguments.get("max_results"),
+            )
 
-            if not matches:
+            if match["status"] == "clarification":
                 return [TextContent(type="text", text=(
-                    f"No skills found matching **'{arguments.get('query', '')}'**.\n\n"
-                    "**Suggestions:**\n"
-                    "- Try different keywords or a more specific phrase\n"
+                    "**I need a little more detail to find the right workflow.**\n\n"
+                    "Add the specific task, intended outcome, or document type, then search again.\n\n"
+                    "**Options:**\n"
+                    "- Rephrase with more specific details\n"
                     f"- Use `{prefix}_categories` to browse all skill categories\n"
-                    "- Ask the user to rephrase their request\n\n"
+                    "- Ask the user a short clarifying question\n\n"
                     f"**DO NOT call `{prefix}_execute`** — no skill has been selected."
                 ))]
 
-            lines = [f"**{len(matches)} skills found for '{arguments.get('query', '')}':**\n"]
-            for i, s in enumerate(matches, 1):
-                desc = s.get("description", "")[:100]
-                lines.append(f"{i}. **{s['name']}** (`{s['id']}`)\n   {desc}\n")
+            matches = match["results"]
+            top_confidence = matches[0]["confidence"]
+            lines = [
+                f"**{len(matches)} recommended workflow{'s' if len(matches) != 1 else ''} "
+                f"({top_confidence} confidence):**\n"
+            ]
+            for i, result in enumerate(matches, 1):
+                desc = result.get("description", "")[:100]
+                lines.append(
+                    f"{i}. **{result['name']}** (`{result['skill_id']}`)\n"
+                    f"   {desc}\n"
+                )
+
+            if match["has_more"]:
+                lines.append(
+                    f"More qualifying workflows are available. Search again with `max_results` greater than "
+                    f"{len(matches)} (maximum 10) to show more.\n"
+                )
 
             lines.append("---")
             lines.append(
@@ -1371,7 +1472,7 @@ async def call_tool(name, arguments):
 
         # ── Categories ────────────────────────────────────────────────────────
         elif name == f"{prefix}_categories":
-            skills = await get_skills()
+            skills = _skills_cache if _skills_cache is not None else []
             cats: dict[str, int] = {}
             for s in skills:
                 cat = s.get("category_id") or s.get("category", "General")
@@ -1419,6 +1520,7 @@ async def main():
     # Load vertical metadata + abbreviations before accepting connections
     await load_vertical()
     await load_abbreviations()
+    await load_discovery_snapshot()
     _rebuild_tools()
 
     # Ping first-connection tracker (idempotent — API only records it once)
@@ -1431,6 +1533,7 @@ async def main():
     import sys as _sys
     print(f"[OK] {v.get('product_name', 'TasksAI')} MCP Server ready (v{SERVER_VERSION})", file=_sys.stderr, flush=True)
     print(f"     Abbreviations: {abbrev_count} loaded from {abbrev_src}", file=_sys.stderr, flush=True)
+    print(f"     Matcher: {POLICY_VERSION} | Discovery metadata loaded before prompts", file=_sys.stderr, flush=True)
     print(f"     Vertical: {v.get('product_id', 'unknown')} | "
           f"Tools: {v.get('tool_prefix', 'tasksai')}_search / execute / save_document / balance / categories",
           file=_sys.stderr, flush=True)

package/runtime/skill_matcher.py

@@ -0,0 +1,492 @@
+"""Local, deterministic skill discovery for the TasksAI terminal runtime.
+
+This module is deliberately pure: it performs no network, filesystem, logging,
+or telemetry operations. Public skill metadata and product-scoped triggers are
+provided by the caller from a snapshot loaded before a discovery request.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from collections.abc import Iterable, Mapping, Sequence
+
+
+POLICY_VERSION = "tasksai-trigger-matcher/2.0"
+
+DEFAULT_STOP_WORDS = {
+    "a", "an", "and", "are", "as", "at", "be", "by", "can", "create",
+    "document", "for", "from", "in", "is", "it", "its", "of", "on",
+    "or", "the", "to", "was", "with",
+}
+
+DEFAULT_CONTEXT_WORDS = {
+    "accounting": {"accountant", "accounting", "bookkeeping", "finance"},
+    "chiropractor": {"chiropractic", "chiropractor", "patient", "practice"},
+    "church": {"church", "congregation", "ministry", "parish"},
+    "contractor": {"build", "construction", "contractor", "project"},
+    "dentist": {"dental", "dentist", "patient", "practice"},
+    "designer": {"creative", "design", "designer", "project"},
+    "electrician": {"electrical", "electrician", "installation", "project"},
+    "eventplanner": {"event", "guest", "planning", "venue"},
+    "farmer": {"agriculture", "crop", "farm", "farmer", "farming", "livestock"},
+    "funeral": {"family", "funeral", "memorial", "service"},
+    "hr": {"employee", "employment", "human resources", "workplace"},
+    "insurance": {"claim", "coverage", "insurance", "policy"},
+    "landlord": {"landlord", "property", "rental", "tenant"},
+    "law": {"attorney", "client", "court", "law", "legal", "litigation"},
+    "marketing": {"audience", "brand", "campaign", "marketing"},
+    "militaryspouse": {"deployment", "military", "military spouse", "relocation"},
+    "mortgage": {"borrower", "loan", "mortgage", "property"},
+    "mortuary": {"funeral", "memorial", "mortuary", "service"},
+    "nutritionist": {"client", "diet", "nutrition", "nutritionist"},
+    "pastor": {"church", "congregation", "ministry", "pastor"},
+    "personaltrainer": {"client", "exercise", "fitness", "training"},
+    "plumber": {"installation", "plumber", "plumbing", "project"},
+    "principal": {"education", "principal", "school", "student"},
+    "realtor": {"buyer", "listing", "property", "real estate", "seller"},
+    "restaurant": {"food service", "guest", "restaurant", "staff"},
+    "salon": {"beauty", "client", "salon", "stylist"},
+    "teacher": {"classroom", "education", "student", "teacher"},
+    "therapist": {"client", "mental health", "patient", "therapy"},
+    "travelagent": {"client", "destination", "travel", "traveler"},
+    "vet": {"animal", "patient", "practice", "veterinary"},
+}
+
+DEFAULT_THRESHOLDS = {"high": 90, "medium": 45}
+DEFAULT_RESULT_COUNT = 3
+MAXIMUM_RESULT_COUNT = 10
+
+
+def normalize_text(value: object) -> str:
+    """NFKC/casefold text and replace punctuation and separators with spaces."""
+    text = unicodedata.normalize("NFKC", str(value or "")).casefold()
+    normalized = "".join(char if char.isalnum() else " " for char in text)
+    return " ".join(normalized.split())
+
+
+def _tokens(value: object) -> tuple[str, ...]:
+    normalized = normalize_text(value)
+    return tuple(normalized.split()) if normalized else ()
+
+
+def _canonical_product_id(value: object) -> str:
+    product_id = normalize_text(value).replace(" ", "")
+    aliases = {
+        "farmertasksai": "farmer",
+        "lawtasksai": "law",
+        "realtortasksai": "realtor",
+    }
+    return aliases.get(product_id, product_id)
+
+
+def _declared_product_ids(record: Mapping[str, object]) -> set[str]:
+    values: list[object] = []
+    for key in ("product_id", "vertical_id"):
+        if record.get(key):
+            values.append(record[key])
+
+    product = record.get("product")
+    if isinstance(product, Mapping):
+        for key in ("product_id", "id", "slug"):
+            if product.get(key):
+                values.append(product[key])
+    elif product:
+        values.append(product)
+
+    product_ids = record.get("product_ids")
+    if isinstance(product_ids, Sequence) and not isinstance(product_ids, (str, bytes)):
+        values.extend(product_ids)
+
+    return {_canonical_product_id(value) for value in values if _canonical_product_id(value)}
+
+
+def _belongs_to_product(record: Mapping[str, object], product_id: str) -> bool:
+    declared = _declared_product_ids(record)
+    return not declared or _canonical_product_id(product_id) in declared
+
+
+def _expand_abbreviations(
+    tokens: tuple[str, ...], abbreviations: Mapping[str, object]
+) -> tuple[str, ...]:
+    expansions: list[tuple[tuple[str, ...], tuple[str, ...]]] = []
+    for abbreviation, expansion in abbreviations.items():
+        abbreviation_tokens = _tokens(abbreviation)
+        expansion_tokens = _tokens(expansion)
+        if abbreviation_tokens and expansion_tokens:
+            expansions.append((abbreviation_tokens, expansion_tokens))
+    expansions.sort(key=lambda item: (-len(item[0]), item[0]))
+
+    expanded: list[str] = []
+    index = 0
+    while index < len(tokens):
+        match = next(
+            (
+                (abbreviation_tokens, expansion_tokens)
+                for abbreviation_tokens, expansion_tokens in expansions
+                if tokens[index:index + len(abbreviation_tokens)] == abbreviation_tokens
+            ),
+            None,
+        )
+        if match is None:
+            expanded.append(tokens[index])
+            index += 1
+            continue
+        abbreviation_tokens, expansion_tokens = match
+        expanded.extend(expansion_tokens)
+        index += len(abbreviation_tokens)
+    return tuple(expanded)
+
+
+def _normalize_scoring_tokens(
+    value: object,
+    stop_words: set[str],
+    abbreviations: Mapping[str, object],
+) -> tuple[str, ...]:
+    expanded = _expand_abbreviations(_tokens(value), abbreviations)
+    return tuple(token for token in expanded if token not in stop_words)
+
+
+def _contains_tokens(container: tuple[str, ...], candidate: tuple[str, ...]) -> bool:
+    if not candidate or len(candidate) > len(container):
+        return False
+    width = len(candidate)
+    return any(container[index:index + width] == candidate for index in range(len(container) - width + 1))
+
+
+def _category_text(skill: Mapping[str, object]) -> str:
+    category = skill.get("category")
+    if isinstance(category, Mapping):
+        category = category.get("name") or category.get("id") or ""
+    return " ".join(
+        str(value)
+        for value in (category, skill.get("category_name"), skill.get("category_id"))
+        if value
+    )
+
+
+def _family_id(skill: Mapping[str, object]) -> str:
+    family = skill.get("family")
+    if isinstance(family, Mapping):
+        family = family.get("id") or family.get("name") or ""
+    value = skill.get("family_id") or skill.get("skill_family_id") or family
+    return normalize_text(value)
+
+
+def _trigger_values(
+    triggers: Mapping[str, object], skill_id: str, product_id: str
+) -> tuple[str, ...]:
+    value = triggers.get(skill_id, ())
+    if isinstance(value, Mapping):
+        if not _belongs_to_product(value, product_id):
+            return ()
+        value = value.get("triggers", ())
+    if isinstance(value, str):
+        value = (value,)
+    if not isinstance(value, Iterable):
+        return ()
+    return tuple(str(trigger) for trigger in value if str(trigger).strip())
+
+
+def _resolve_config(product_id: str, config: Mapping[str, object] | None) -> tuple[dict, list[str]]:
+    diagnostics: list[str] = []
+    config_product = _canonical_product_id(config.get("product_id")) if config else ""
+    valid_config = (
+        config
+        if config
+        and config.get("policy_version") == POLICY_VERSION
+        and (not config_product or config_product == _canonical_product_id(product_id))
+        else None
+    )
+    if valid_config is None:
+        if config is None:
+            diagnostics.append("bundled_policy_defaults")
+        elif config.get("policy_version") != POLICY_VERSION:
+            diagnostics.append("bundled_policy_defaults:policy_version_mismatch")
+        else:
+            diagnostics.append("bundled_policy_defaults:product_mismatch")
+
+    source = valid_config or {}
+    supplied_stop_words = source.get("stop_words", DEFAULT_STOP_WORDS)
+    if not isinstance(supplied_stop_words, Sequence) or isinstance(supplied_stop_words, (str, bytes)):
+        supplied_stop_words = DEFAULT_STOP_WORDS
+    stop_words = {
+        token
+        for value in supplied_stop_words
+        for token in _tokens(value)
+    }
+    context_default = DEFAULT_CONTEXT_WORDS.get(_canonical_product_id(product_id), set())
+    supplied_context_words = source.get("context_words", context_default)
+    if not isinstance(supplied_context_words, Sequence) or isinstance(supplied_context_words, (str, bytes)):
+        supplied_context_words = context_default
+    context_words = {
+        token
+        for value in supplied_context_words
+        for token in _tokens(value)
+    }
+    thresholds = dict(DEFAULT_THRESHOLDS)
+    supplied_thresholds = source.get("thresholds")
+    if isinstance(supplied_thresholds, Mapping):
+        for key in ("high", "medium"):
+            value = supplied_thresholds.get(key)
+            if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+                thresholds[key] = value
+    if thresholds["high"] < 1 or thresholds["medium"] > thresholds["high"]:
+        diagnostics.append("bundled_thresholds:invalid_order")
+        thresholds = dict(DEFAULT_THRESHOLDS)
+
+    default_count = source.get("default_result_count", DEFAULT_RESULT_COUNT)
+    maximum_count = source.get("maximum_result_count", MAXIMUM_RESULT_COUNT)
+    if not isinstance(default_count, int) or isinstance(default_count, bool) or default_count < 1:
+        default_count = DEFAULT_RESULT_COUNT
+    if not isinstance(maximum_count, int) or isinstance(maximum_count, bool) or maximum_count < 1:
+        maximum_count = MAXIMUM_RESULT_COUNT
+    maximum_count = min(maximum_count, MAXIMUM_RESULT_COUNT)
+    default_count = min(default_count, maximum_count)
+
+    configured_abbreviations = source.get("abbreviations", {})
+    if not isinstance(configured_abbreviations, Mapping):
+        configured_abbreviations = {}
+
+    return {
+        "stop_words": stop_words,
+        "context_words": context_words,
+        "thresholds": thresholds,
+        "default_result_count": default_count,
+        "maximum_result_count": maximum_count,
+        "abbreviations": configured_abbreviations,
+    }, diagnostics
+
+
+def _score_trigger(
+    query_tokens: tuple[str, ...],
+    trigger: str,
+    stop_words: set[str],
+    context_words: set[str],
+    abbreviations: Mapping[str, object],
+) -> tuple[int, int, set[str], str]:
+    trigger_tokens = _normalize_scoring_tokens(trigger, stop_words, abbreviations)
+    if not trigger_tokens:
+        return 0, 0, set(), ""
+
+    query_set = set(query_tokens)
+    trigger_set = set(trigger_tokens)
+    matched = query_set & trigger_set
+    specific_tokens = trigger_set - context_words
+    specificity = len(specific_tokens)
+
+    if query_tokens == trigger_tokens:
+        return 120, specificity, matched, "trigger_exact"
+    if _contains_tokens(query_tokens, trigger_tokens):
+        bonus = min(15, max(0, specificity - 1) * 3)
+        return 90 + bonus, specificity, matched, "trigger_complete"
+    query_specific = query_set - context_words
+    if len(query_specific) >= 2 and _contains_tokens(trigger_tokens, query_tokens):
+        return 70, specificity, matched, "trigger_query_complete"
+
+    coverage_tokens = specific_tokens or trigger_set
+    covered = query_set & coverage_tokens
+    coverage = len(covered) / len(coverage_tokens)
+    if len(covered) >= 2 and coverage >= 0.67:
+        return round(40 * coverage), specificity, matched, "trigger_partial"
+    return 0, specificity, set(), ""
+
+
+def _score_skill(
+    skill: Mapping[str, object],
+    query_tokens: tuple[str, ...],
+    triggers: Mapping[str, object],
+    product_id: str,
+    policy: Mapping[str, object],
+) -> dict:
+    stop_words = policy["stop_words"]
+    context_words = policy["context_words"]
+    abbreviations = policy["abbreviations"]
+    query_set = set(query_tokens)
+    specific_query = query_set - context_words
+    context_query = query_set & context_words
+    skill_id = str(skill.get("id", ""))
+
+    strongest_trigger = (0, 0, set(), "", "")
+    for trigger in _trigger_values(triggers, skill_id, product_id):
+        score, specificity, matched, evidence = _score_trigger(
+            query_tokens, trigger, stop_words, context_words, abbreviations
+        )
+        candidate = (score, specificity, matched, evidence, normalize_text(trigger))
+        candidate_key = (score, specificity, len(matched), normalize_text(trigger))
+        strongest_key = (
+            strongest_trigger[0],
+            strongest_trigger[1],
+            len(strongest_trigger[2]),
+            strongest_trigger[4],
+        )
+        if candidate_key > strongest_key:
+            strongest_trigger = candidate
+
+    trigger_score, trigger_specificity, trigger_matched, trigger_evidence, _ = strongest_trigger
+    evidence = [trigger_evidence] if trigger_evidence else []
+    matched_tokens = set(trigger_matched)
+
+    name_tokens = _normalize_scoring_tokens(
+        skill.get("name", ""), stop_words, abbreviations
+    )
+    name_set = set(name_tokens)
+    identity_score = 0
+    if name_tokens and _contains_tokens(query_tokens, name_tokens):
+        identity_score += 35
+        evidence.append("name_complete")
+    for token in sorted(specific_query & name_set):
+        identity_score += 8
+        matched_tokens.add(token)
+        evidence.append(f"name:{token}")
+    for token in sorted(context_query & name_set):
+        identity_score += 3
+        matched_tokens.add(token)
+        evidence.append(f"name_context:{token}")
+
+    category_set = set(
+        _normalize_scoring_tokens(_category_text(skill), stop_words, abbreviations)
+    )
+    category_score = 0
+    for token in sorted(specific_query & category_set):
+        category_score += 3
+        matched_tokens.add(token)
+        evidence.append(f"category:{token}")
+    for token in sorted(context_query & category_set):
+        category_score += 1
+        matched_tokens.add(token)
+        evidence.append(f"category_context:{token}")
+
+    description_set = set(
+        _normalize_scoring_tokens(skill.get("description", ""), stop_words, abbreviations)
+    )
+    description_matches = sorted(specific_query & description_set)
+    description_score = len(description_matches)
+    for token in description_matches:
+        matched_tokens.add(token)
+        evidence.append(f"description:{token}")
+
+    score = trigger_score + identity_score + category_score + description_score
+    if trigger_score == identity_score == category_score == 0:
+        score = min(score, policy["thresholds"]["high"] - 1)
+
+    if score >= policy["thresholds"]["high"]:
+        confidence = "high"
+    elif score >= policy["thresholds"]["medium"]:
+        confidence = "medium"
+    else:
+        confidence = "low"
+
+    return {
+        "skill_id": skill_id,
+        "name": str(skill.get("name", "")),
+        "description": str(skill.get("description", "")),
+        "category": _category_text(skill),
+        "score": score,
+        "confidence": confidence,
+        "evidence": evidence,
+        "_trigger_specificity": trigger_specificity,
+        "_matched_tokens": matched_tokens,
+        "_description_normalized": normalize_text(skill.get("description", "")),
+        "_family_id": _family_id(skill),
+    }
+
+
+def _sort_key(result: Mapping[str, object]) -> tuple:
+    return (
+        -result["score"],
+        -result["_trigger_specificity"],
+        -len(result["_matched_tokens"]),
+        normalize_text(result["name"]),
+        str(result["skill_id"]),
+    )
+
+
+def _diversify(results: list[dict]) -> list[dict]:
+    diversified: list[dict] = []
+    seen_ids: set[str] = set()
+    seen_descriptions: set[str] = set()
+    family_counts: dict[str, int] = {}
+    for result in results:
+        skill_id = result["skill_id"]
+        description = result["_description_normalized"]
+        family_id = result["_family_id"]
+        if skill_id in seen_ids:
+            continue
+        if description and description in seen_descriptions:
+            continue
+        if family_id and family_counts.get(family_id, 0) >= 2:
+            continue
+        diversified.append(result)
+        seen_ids.add(skill_id)
+        if description:
+            seen_descriptions.add(description)
+        if family_id:
+            family_counts[family_id] = family_counts.get(family_id, 0) + 1
+    return diversified
+
+
+def match_skills(
+    query: str,
+    skills: Sequence[Mapping[str, object]],
+    triggers: Mapping[str, object],
+    product_id: str,
+    *,
+    abbreviations: Mapping[str, object] | None = None,
+    config: Mapping[str, object] | None = None,
+    result_count: int | None = None,
+) -> dict:
+    """Rank product-scoped public skill metadata under matcher policy 2.0."""
+    if not product_id or not _canonical_product_id(product_id):
+        raise ValueError("product_id is required for product-isolated matching")
+
+    policy, diagnostics = _resolve_config(product_id, config)
+    configured_abbreviations = dict(policy["abbreviations"])
+    if abbreviations:
+        configured_abbreviations.update(abbreviations)
+    policy["abbreviations"] = configured_abbreviations
+
+    raw_tokens = _tokens(query)
+    expanded_tokens = _expand_abbreviations(raw_tokens, configured_abbreviations)
+    query_tokens = tuple(token for token in expanded_tokens if token not in policy["stop_words"])
+    query_normalized = " ".join(query_tokens)
+
+    requested_count = policy["default_result_count"] if result_count is None else result_count
+    if not isinstance(requested_count, int) or isinstance(requested_count, bool):
+        requested_count = policy["default_result_count"]
+    requested_count = max(1, min(requested_count, policy["maximum_result_count"]))
+
+    scoped_skills = [skill for skill in skills if _belongs_to_product(skill, product_id)]
+    if len(scoped_skills) != len(skills):
+        diagnostics.append("product_mismatches_filtered")
+
+    ranked = [
+        _score_skill(skill, query_tokens, triggers, product_id, policy)
+        for skill in scoped_skills
+        if skill.get("id")
+    ]
+    ranked.sort(key=_sort_key)
+    qualified = [
+        result
+        for result in _diversify(ranked)
+        if result["confidence"] in {"high", "medium"}
+    ]
+    selected = qualified[:requested_count]
+
+    public_results = []
+    for result in selected:
+        public_results.append({
+            key: value
+            for key, value in result.items()
+            if not key.startswith("_")
+        })
+
+    return {
+        "policy_version": POLICY_VERSION,
+        "status": "matched" if public_results else "clarification",
+        "query_normalized": query_normalized,
+        "results": public_results,
+        "total_qualified": len(qualified),
+        "has_more": len(qualified) > len(public_results),
+        "result_count": requested_count,
+        "diagnostics": diagnostics,
+    }

package/src/index.js

@@ -732,8 +732,10 @@ async function checkWritable({ label, targetPath, kind }) {
 async function downloadRuntime(source, runtimeDir, manifest = {}) {
   const useBundledRuntime = manifest.runtime?.source === "shared_installer";
   const serverText = await loadRuntimeText(source, "server.py", { useBundledRuntime });
+  const matcherText = await loadRuntimeText(source, "skill_matcher.py", { useBundledRuntime });
   const requirementsText = await loadRuntimeText(source, "requirements.txt", { useBundledRuntime });
   await fsp.writeFile(path.join(runtimeDir, "server.py"), serverText, "utf8");
+  await fsp.writeFile(path.join(runtimeDir, "skill_matcher.py"), matcherText, "utf8");
   await fsp.writeFile(path.join(runtimeDir, "requirements.txt"), requirementsText, "utf8");
 }