codenib 0.1.0__py3-none-any.whl

codenib/__init__.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Public CodeNib API.
+
+Exports are resolved lazily so importing :mod:`codenib` or starting the CLI
+does not initialize optional graph, embedding, and agent runtimes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._lazy import exported_dir, load_export
+from ._version import __version__
+
+_EXPORTS = {
+    "LSIndexer": ("codenib.ls_router", "LSIndexer"),
+    "CodeGraph": ("codenib.graph.code_graph", "CodeGraph"),
+    "BM25CodeIndexer": (
+        "codenib.index.sparse_idx.bm25_index",
+        "BM25CodeIndexer",
+    ),
+    "KeywordExtractor": ("codenib.agent.extract_agent", "KeywordExtractor"),
+    "CodeSearchEngine": ("codenib.search", "CodeSearchEngine"),
+    "RerankAgent": ("codenib.agent.rerank_agent", "RerankAgent"),
+    "CodeChunker": ("codenib.code_chunker", "CodeChunker"),
+    "RepoChunkingConfig": ("codenib.code_chunker", "RepoChunkingConfig"),
+    "RegexNodeIndex": ("codenib.index.regex_idx", "RegexNodeIndex"),
+    "CodeVectorStore": (
+        "codenib.index.embedding.vector_store",
+        "CodeVectorStore",
+    ),
+    "create_code_vector_store": (
+        "codenib.index.embedding.vector_store",
+        "create_code_vector_store",
+    ),
+}
+
+__all__ = [
+    "__version__",
+    "LSIndexer",
+    "CodeGraph",
+    "BM25CodeIndexer",
+    "KeywordExtractor",
+    "CodeSearchEngine",
+    "RerankAgent",
+    "CodeChunker",
+    "RepoChunkingConfig",
+    "RegexNodeIndex",
+    "CodeVectorStore",
+    "create_code_vector_store",
+]
+
+
+def __getattr__(name: str) -> Any:
+    return load_export(globals(), _EXPORTS, name)
+
+
+def __dir__() -> list[str]:
+    return exported_dir(globals(), _EXPORTS)

codenib/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .cli import main
+
+raise SystemExit(main())

codenib/_lazy.py

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Small helper for preserving package APIs without eager imports."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, Mapping, MutableMapping
+
+LazyExports = Mapping[str, tuple[str, str]]
+
+
+def load_export(
+    namespace: MutableMapping[str, Any],
+    exports: LazyExports,
+    name: str,
+) -> Any:
+    """Import, cache, and return one declared package export."""
+    target = exports.get(name)
+    if target is None:
+        module_name = namespace.get("__name__", "module")
+        raise AttributeError(f"module {module_name!r} has no attribute {name!r}")
+    module_name, attribute = target
+    value = getattr(import_module(module_name), attribute)
+    namespace[name] = value
+    return value
+
+
+def exported_dir(namespace: Mapping[str, Any], exports: LazyExports) -> list[str]:
+    """Include lazy exports in ``dir(package)``."""
+    return sorted(set(namespace) | set(exports))
+
+
+__all__ = ["LazyExports", "exported_dir", "load_export"]

codenib/_version.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Installed CodeNib version.
+
+``pyproject.toml`` is the only authored version source. Package metadata makes
+that value available at runtime without importing optional CodeNib subsystems.
+"""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+
+def package_version() -> str:
+    """Return the installed distribution version."""
+    try:
+        return metadata.version("codenib")
+    except metadata.PackageNotFoundError:
+        return "0+unknown"
+
+
+__version__ = package_version()
+
+__all__ = ["__version__", "package_version"]

codenib/agent/__init__.py

@@ -0,0 +1,159 @@
+# SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent package consolidating agent utilities and implementations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._lazy import exported_dir, load_export
+
+_EXPORTS = {
+    "AgentResult": ("codenib.agent.agent_types", "AgentResult"),
+    "ToolCallRecord": ("codenib.agent.agent_types", "ToolCallRecord"),
+    "KeywordExtraction": ("codenib.agent.extract_agent", "KeywordExtraction"),
+    "KeywordExtractor": ("codenib.agent.extract_agent", "KeywordExtractor"),
+    "extract_keywords_from_statement": (
+        "codenib.agent.extract_agent",
+        "extract_keywords_from_statement",
+    ),
+    "AgentHarnessSpec": ("codenib.agent.harness", "AgentHarnessSpec"),
+    "AgentRunAccumulator": ("codenib.agent.harness", "AgentRunAccumulator"),
+    "agent_working_directory": (
+        "codenib.agent.harness",
+        "agent_working_directory",
+    ),
+    "run_agent_in_directory": (
+        "codenib.agent.harness",
+        "run_agent_in_directory",
+    ),
+    "PlainChatHistory": ("codenib.agent.history", "PlainChatHistory"),
+    "TokenBudgetedChatHistory": (
+        "codenib.agent.history",
+        "TokenBudgetedChatHistory",
+    ),
+    "count_message_tokens": ("codenib.agent.history", "count_message_tokens"),
+    "LSPProviderMetadata": (
+        "codenib.agent.lsp_provider",
+        "LSPProviderMetadata",
+    ),
+    "LSPProviderNodes": ("codenib.agent.lsp_provider", "LSPProviderNodes"),
+    "StaticLSPProvider": ("codenib.agent.lsp_provider", "StaticLSPProvider"),
+    "lsp_result_metadata": (
+        "codenib.agent.lsp_provider",
+        "lsp_result_metadata",
+    ),
+    "RerankAgent": ("codenib.agent.rerank_agent", "RerankAgent"),
+    "RerankResult": ("codenib.agent.rerank_agent", "RerankResult"),
+    "rerank_nodes_with_query": (
+        "codenib.agent.rerank_agent",
+        "rerank_nodes_with_query",
+    ),
+    "LSPRouteContext": ("codenib.agent.route_context", "LSPRouteContext"),
+    "build_lsp_route_context": (
+        "codenib.agent.route_context",
+        "build_lsp_route_context",
+    ),
+    "canonical_lsp_route_args": (
+        "codenib.agent.route_context",
+        "canonical_lsp_route_args",
+    ),
+    "extract_lsp_symbol_seeds": (
+        "codenib.agent.route_context",
+        "extract_lsp_symbol_seeds",
+    ),
+    "filter_lsp_symbol_seeds": (
+        "codenib.agent.route_context",
+        "filter_lsp_symbol_seeds",
+    ),
+    "fingerprint_lsp_route_nodes": (
+        "codenib.agent.route_context",
+        "fingerprint_lsp_route_nodes",
+    ),
+    "is_specific_lsp_symbol_seed": (
+        "codenib.agent.route_context",
+        "is_specific_lsp_symbol_seed",
+    ),
+    "normalize_lsp_route_seed_policy": (
+        "codenib.agent.route_context",
+        "normalize_lsp_route_seed_policy",
+    ),
+    "render_lsp_route_context": (
+        "codenib.agent.route_context",
+        "render_lsp_route_context",
+    ),
+    "AgentRunner": ("codenib.agent.runner", "AgentRunner"),
+    "CodeNibAgentOptions": ("codenib.agent.runner", "CodeNibAgentOptions"),
+    "compile_repo": ("codenib.agent.runner", "compile_repo"),
+    "has_localization_contract": (
+        "codenib.agent.runner",
+        "has_localization_contract",
+    ),
+    "query": ("codenib.agent.runner", "query"),
+    "AGENT_TRACE_SCHEMA_VERSION": (
+        "codenib.agent.runtime",
+        "AGENT_TRACE_SCHEMA_VERSION",
+    ),
+    "AgentRunTrace": ("codenib.agent.runtime", "AgentRunTrace"),
+    "AgentTraceEvent": ("codenib.agent.runtime", "AgentTraceEvent"),
+    "ContextLedger": ("codenib.agent.runtime", "ContextLedger"),
+    "ContextLedgerEntry": ("codenib.agent.runtime", "ContextLedgerEntry"),
+    "registry_to_tools": ("codenib.agent.tool_schema", "registry_to_tools"),
+    "skill_to_tool_schema": (
+        "codenib.agent.tool_schema",
+        "skill_to_tool_schema",
+    ),
+}
+
+__all__ = [
+    "AgentResult",
+    "AgentRunTrace",
+    "AgentRunAccumulator",
+    "AgentTraceEvent",
+    "AgentRunner",
+    "AGENT_TRACE_SCHEMA_VERSION",
+    "AgentHarnessSpec",
+    "CodeNibAgentOptions",
+    "ContextLedger",
+    "ContextLedgerEntry",
+    "KeywordExtraction",
+    "KeywordExtractor",
+    "LSPRouteContext",
+    "LSPProviderMetadata",
+    "LSPProviderNodes",
+    "PlainChatHistory",
+    "RerankAgent",
+    "RerankResult",
+    "TokenBudgetedChatHistory",
+    "ToolCallRecord",
+    "StaticLSPProvider",
+    "agent_working_directory",
+    "compile_repo",
+    "count_message_tokens",
+    "build_lsp_route_context",
+    "canonical_lsp_route_args",
+    "extract_keywords_from_statement",
+    "extract_lsp_symbol_seeds",
+    "filter_lsp_symbol_seeds",
+    "fingerprint_lsp_route_nodes",
+    "has_localization_contract",
+    "is_specific_lsp_symbol_seed",
+    "lsp_result_metadata",
+    "normalize_lsp_route_seed_policy",
+    "query",
+    "rerank_nodes_with_query",
+    "render_lsp_route_context",
+    "registry_to_tools",
+    "run_agent_in_directory",
+    "skill_to_tool_schema",
+]
+
+
+def __getattr__(name: str) -> Any:
+    return load_export(globals(), _EXPORTS, name)
+
+
+def __dir__() -> list[str]:
+    return exported_dir(globals(), _EXPORTS)

codenib/agent/agent_types.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Data types for the agent runner."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from ..llm.usage import TokenUsage, UsageRecord
+from .runtime.trace import AgentRunTrace
+
+
+@dataclass
+class ToolCallRecord:
+    """Record of a single tool invocation during an agent run."""
+
+    tool_call_id: str
+    skill_id: str
+    arguments: Dict[str, Any]
+    resolved_arguments: Optional[Dict[str, Any]] = None
+    result: Any = None
+    duration_ms: float = 0.0
+    error: Optional[str] = None
+
+
+@dataclass
+class AgentResult:
+    """Outcome of ``AgentRunner.run()``."""
+
+    answer: str
+    tool_calls: List[ToolCallRecord] = field(default_factory=list)
+    messages: List[Dict[str, Any]] = field(default_factory=list)
+    total_turns: int = 0
+    total_duration_ms: float = 0.0
+    usage: Optional[TokenUsage] = None
+    usage_records: List[UsageRecord] = field(default_factory=list)
+    trace: Optional[AgentRunTrace] = None

codenib/agent/boundary.py

@@ -0,0 +1,129 @@
+# SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent-boundary line-numbering conversion (issue #153).
+
+Internal representations are uniformly **0-based**: BM25 docs, FAISS
+metadata, symbol-graph anchors, and the tree-sitter ``CodeChunk`` all count
+lines from 0. The *agent boundary* is **1-based outward** -- line numbers
+shown to, and accepted back from, the LLM are 1-based, mirroring the
+``CodeLocation`` convention already used at the dataset/HuggingFace boundary
+(see ``_chunk_to_code_block`` in ``dataset/gt_locate.py``, which does the
+same ``+1`` once).
+
+Without a single conversion site there is a silent 0/1 split *inside one
+result*: a ``bm25_search`` hit renders its ``content`` gutter 1-based (via
+``wrap_code_snippet(start_line + 1, ...)``) while its structured
+``start_line`` stays 0-based, so an LLM that reads "line 42" from the
+snippet and feeds it back as a seed into ``graph_expand`` hits an
+off-by-one that never raises.
+
+Two helpers, one conversion each:
+
+- :func:`to_agent_repr` -- serialize a result node for the LLM (``+1``).
+- :func:`from_agent_repr` -- parse a line number coming back (``-1``).
+
+Internals stay 0-based; only these two functions touch the offset.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+# The LLM sees 1-based lines; every internal index is 0-based.
+AGENT_LINE_OFFSET = 1
+
+# Structured fields carrying a line number on a result node.
+_LINE_FIELDS = ("start_line", "end_line")
+
+
+def _is_int_line(val: Any) -> bool:
+    """Whether *val* is a real integer line number.
+
+    ``bool`` is an ``int`` subclass; exclude it defensively so a stray
+    ``True``/``False`` is never shifted as if it were line ``1``/``0``.
+    """
+    return isinstance(val, int) and not isinstance(val, bool)
+
+
+def is_line_bearing(obj: Any) -> bool:
+    """Whether *obj* is a result node that carries line-number fields.
+
+    Used to decide whether :func:`to_agent_repr` should be applied during
+    serialization; non-node results (bare strings, scores, dicts without
+    line fields) are left untouched.
+    """
+    if isinstance(obj, dict):
+        return "start_line" in obj or "end_line" in obj
+    return hasattr(obj, "start_line") or hasattr(obj, "end_line")
+
+
+def to_agent_repr(node: Any) -> Dict[str, Any]:
+    """Serialize a result node to a 1-based dict for the LLM.
+
+    Accepts a pydantic ``NodeInfo`` / ``QueriedNode``, a plain object with
+    ``__dict__``, or a mapping. Returns a plain dict with ``start_line`` /
+    ``end_line`` shifted ``+1`` (0-based -> 1-based). ``None`` line values
+    are preserved; all other fields pass through unchanged.
+    """
+    data = _as_dict(node)
+    for fld in _LINE_FIELDS:
+        val = data.get(fld)
+        if _is_int_line(val):
+            data[fld] = val + AGENT_LINE_OFFSET
+    return data
+
+
+def from_agent_repr(line: Optional[int]) -> Optional[int]:
+    """Convert a single 1-based line number from the LLM to 0-based.
+
+    ``None`` passes through. A malformed seed (the LLM emitting ``0`` or a
+    negative, which is not a valid 1-based line) is clamped at ``0`` so it
+    can never produce a negative internal index.
+    """
+    if line is None or isinstance(line, bool):
+        return line
+    converted = int(line) - AGENT_LINE_OFFSET
+    return converted if converted >= 0 else 0
+
+
+def from_agent_repr_arg(value: Any) -> Any:
+    """Apply :func:`from_agent_repr` across a whole tool argument.
+
+    Handles the shapes a line-bearing skill argument can take:
+
+    - a scalar line number,
+    - a list/tuple of line numbers,
+    - a list of ``[start, end]`` pairs, or
+    - ``{"start_line": ..., "end_line": ...}`` range dicts.
+
+    Any other shape passes through unchanged. This is the input-side
+    counterpart wired into :class:`~codenib.agent.runner.AgentRunner` for
+    skill inputs marked ``is_line_number`` (e.g. ``graph_expand`` ranges,
+    ``read_code_block``).
+    """
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return from_agent_repr(value)
+    if isinstance(value, (list, tuple)):
+        return type(value)(from_agent_repr_arg(v) for v in value)
+    if isinstance(value, dict):
+        out = dict(value)
+        for fld in _LINE_FIELDS:
+            if _is_int_line(out.get(fld)):
+                out[fld] = from_agent_repr(out[fld])
+        return out
+    return value
+
+
+def _as_dict(node: Any) -> Dict[str, Any]:
+    """Best-effort conversion of a result node to a mutable dict."""
+    if isinstance(node, dict):
+        return dict(node)
+    if hasattr(node, "model_dump"):
+        return node.model_dump(exclude_none=True)
+    if hasattr(node, "__dict__"):
+        return dict(node.__dict__)
+    return {"value": node}

codenib/agent/compile.py

@@ -0,0 +1,219 @@
+# SPDX-FileCopyrightText: 2025-2026 CodeNib Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Agent compile: query-time skill selection.
+
+Implements the lookup mechanism from issue #133 (RFC: Agent compile).
+At agent entry, ``classify(query, session_ctx)`` produces a ``Scenario``;
+``agent_compile`` then looks the scenario up in a ``compile_table`` and
+returns the skill subset the agent is allowed to call this turn.
+
+The classifier is deterministic by design. LLM-driven scenario
+classification was explicitly de-scoped in the v2 RFC (open question 3):
+start with rules, revisit once Phase 2 data is in. Two dimensions are
+runtime-computable without GT access:
+
+* ``language`` — taken from ``SessionContext.primary_language`` (which
+  upstream loaders fill from the dataset row or repo metadata).
+* ``has_stacktrace`` — regex sweep over the query text.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, FrozenSet, Iterable, Mapping, Optional, Union
+
+from ..compiler.params import SessionContext
+from ..languages import (
+    agent_language_aliases,
+    normalize_agent_language,
+    supported_agent_languages,
+)
+
+logger = logging.getLogger(__name__)
+
+
+SUPPORTED_LANGUAGES: FrozenSet[str] = supported_agent_languages()
+
+
+# Stack-trace regexes. Each pattern matches a *structural* marker that only
+# appears in a real captured trace — not in user prose mentioning the word
+# "traceback" or "panic". Patterns are anchored where the runtime emits them
+# (line start) and use ``re.MULTILINE`` because problem_statement bodies
+# typically embed traces inline.
+_STACKTRACE_PATTERNS = (
+    # Python — exact runtime banner
+    re.compile(r"Traceback \(most recent call last\):"),
+    # Rust — panic header
+    re.compile(r"thread '[^']+' panicked at", re.IGNORECASE),
+    re.compile(r"\bpanicked at\b 'try '", re.IGNORECASE),  # older rust style
+    # Go — runtime panic line + a goroutine frame
+    re.compile(r"^panic: ", re.MULTILINE),
+    re.compile(r"^goroutine \d+ \[", re.MULTILINE),
+    # JS / TS / Node — stack frames "    at name (file.js:42[:col])"
+    re.compile(
+        r"^\s+at\s+\S+\s*\([^()\n]+:\d+(?::\d+)?\)\s*$",
+        re.MULTILINE,
+    ),
+    # JVM — "\tat com.example.Class.method(File.java:42)"
+    re.compile(r"^\s+at\s+\S+\.\S+\([^()\n]+:\d+\)\s*$", re.MULTILINE),
+    # Ruby — "/app/lib/foo.rb:42:in `bar'" or "\tfrom ...rb:8:in '<main>'"
+    re.compile(
+        r"^\s*(?:from\s+)?[^:\n]+\.rb:\d+:in\s+[`'][^`'\n]+[`']",
+        re.MULTILINE,
+    ),
+    # .NET — "   at Namespace.Type.Method(...) in File.cs:line 42"
+    re.compile(
+        r"^\s+at\s+\S+\.\S+\([^()\n]*\)\s+in\s+[^:\n]+\.cs:line\s+\d+\s*$",
+        re.MULTILINE,
+    ),
+    # PHP — "#0 /app/src/Foo.php(42): Class->method(...)"
+    re.compile(r"^#\d+\s+[^()\n]+\.php\(\d+\):\s+\S+", re.MULTILINE),
+    # C/C++ — addr2line / backtrace lines look like "#0 0x... in fn at file:42"
+    re.compile(r"^#\d+\s+0x[0-9a-fA-F]+\s+in\s+\S+", re.MULTILINE),
+)
+
+
+def detect_stacktrace(query: str) -> bool:
+    """Return True if the query embeds a recognisable runtime stack trace."""
+    if not query:
+        return False
+    return any(p.search(query) for p in _STACKTRACE_PATTERNS)
+
+
+_LANGUAGE_ALIASES: Dict[str, str] = agent_language_aliases()
+
+
+def normalize_language(raw: Optional[str]) -> Optional[str]:
+    """Map a dataset / repo-meta language string to a canonical key.
+
+    Returns ``None`` for unknown or empty inputs so callers can branch on
+    "no language signal" without sentinel strings.
+    """
+    if not raw:
+        return None
+    return normalize_agent_language(raw)
+
+
+@dataclass(frozen=True, slots=True)
+class Scenario:
+    """A (query, repo) bucket used as a compile-table lookup key.
+
+    Two-dimensional per RFC v2 — ``query_length`` and ``query_concreteness``
+    from v1 were dropped to keep the eval cells statistically meaningful.
+    """
+
+    language: Optional[str]
+    has_stacktrace: bool
+
+    def key(self) -> str:
+        """Stable string key for ``compile_table.json`` lookup."""
+        lang = self.language or "unknown"
+        flag = "stacktrace" if self.has_stacktrace else "no_stacktrace"
+        return f"{lang}:{flag}"
+
+    @classmethod
+    def from_key(cls, key: str) -> "Scenario":
+        lang, flag = key.split(":", 1)
+        return cls(
+            language=None if lang == "unknown" else lang,
+            has_stacktrace=(flag == "stacktrace"),
+        )
+
+
+def classify(query: str, session_ctx: Optional[SessionContext]) -> Scenario:
+    """Compute the scenario for a single (query, repo) pair."""
+    lang: Optional[str] = None
+    if session_ctx is not None:
+        lang = normalize_language(session_ctx.primary_language)
+    return Scenario(language=lang, has_stacktrace=detect_stacktrace(query))
+
+
+CompileTable = Mapping[str, Iterable[str]]
+
+
+def load_compile_table(path: Union[str, Path]) -> Dict[str, FrozenSet[str]]:
+    """Load a ``compile_table`` file as a ``{scenario_key: frozenset}`` map.
+
+    Supports JSON (``.json``) and YAML (``.yaml`` / ``.yml``). The on-disk
+    format is a mapping whose keys are the strings returned by
+    :meth:`Scenario.key` and whose values are lists of skill IDs.
+    """
+    p = Path(path)
+    suffix = p.suffix.lower()
+    with p.open("r", encoding="utf-8") as f:
+        if suffix in {".yaml", ".yml"}:
+            import yaml  # local import — PyYAML is already a project dep
+
+            raw = yaml.safe_load(f)
+        elif suffix == ".json":
+            raw = json.load(f)
+        else:
+            raise ValueError(
+                f"compile_table at {p}: unsupported extension {suffix!r}; "
+                "use .json, .yaml, or .yml"
+            )
+    if not isinstance(raw, dict):
+        raise ValueError(
+            f"compile_table at {p} must be a mapping, got {type(raw).__name__}"
+        )
+    out: Dict[str, FrozenSet[str]] = {}
+    for k, v in raw.items():
+        if not isinstance(v, (list, tuple)):
+            raise ValueError(
+                f"compile_table[{k!r}] must be a list of skill IDs, "
+                f"got {type(v).__name__}"
+            )
+        out[k] = frozenset(str(s) for s in v)
+    return out
+
+
+def agent_compile(
+    query: str,
+    session_ctx: Optional[SessionContext],
+    table: Optional[CompileTable] = None,
+) -> Optional[FrozenSet[str]]:
+    """Resolve which skills the agent should be allowed to invoke.
+
+    Args:
+        query: The incoming user query / problem statement.
+        session_ctx: Repo-side context (language, repo size, ...). May be ``None``.
+        table: Mapping from scenario key to skill-ID iterable. ``None`` or empty
+            means "no restriction" — caller should expose the full registry.
+
+    Returns:
+        A ``frozenset`` of skill IDs to allow, or ``None`` to signal "no
+        restriction" (caller falls back to its default, typically A6 = full
+        registry). This matches ``AgentRunner.allow_skills`` semantics where
+        ``None`` means "no filter".
+    """
+    if not table:
+        return None
+    scenario = classify(query, session_ctx)
+    key = scenario.key()
+    if key in table:
+        return frozenset(table[key])
+    logger.warning(
+        "agent_compile: scenario %r not in compile_table (size=%d); "
+        "falling back to full registry",
+        key,
+        len(table),
+    )
+    return None
+
+
+__all__ = [
+    "Scenario",
+    "CompileTable",
+    "SUPPORTED_LANGUAGES",
+    "classify",
+    "detect_stacktrace",
+    "normalize_language",
+    "load_compile_table",
+    "agent_compile",
+]