induscode 0.1.0__py3-none-any.whl

induscode/briefing/skills.py

@@ -0,0 +1,417 @@
+"""Capability-card loader — ``SKILL.md`` discovery, validation, and parsing.
+
+A capability card is *documentation the model reads*: a markdown file in the
+Agent-Skills format whose frontmatter names a skill and one-line-describes
+when it applies, with a body of on-demand instructions. The model decides from
+the ``description`` whether a task matches, then loads the file's ``location``
+to read the full body. This module turns a set of directory roots into
+validated :class:`~induscode.briefing.contract.SkillCard` records plus a
+diagnostic stream.
+
+Discovery follows the format's two shapes, with a generic directory walk
+rather than a special-cased recursion:
+
+- At a *root* level, a direct ``*.md`` child is a single-file skill.
+- In any *subdirectory*, a ``SKILL.md`` file is a packaged skill whose name is
+  expected to match its enclosing directory.
+
+The walk yields candidate file descriptors; a separate validation stage turns
+each candidate into one :class:`~induscode.briefing.contract.SkillDiagnostic`
+(and, on success, one :class:`~induscode.briefing.contract.SkillCard`).
+Validation prose and field policy are the briefing's own; only the *format*
+(frontmatter keys, the ≤64 / ≤1024 limits, lowercase-hyphen names) is the
+shared public spec. Names are deduped across roots — the first card to claim a
+name wins and later claimants are reported as collisions.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import stat as _stat
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from .contract import (
+    SKILL_DESCRIPTION_LIMIT,
+    SKILL_NAME_LIMIT,
+    MacroOrigin,
+    SkillCard,
+    SkillDiagnostic,
+    SkillFrontmatter,
+    SkillLoad,
+    SkillOutcomeKind,
+)
+from .macros import split_frontmatter
+
+__all__ = [
+    "SkillRoot",
+    "gather_skill_cards",
+    "load_skill_cards",
+    "model_invocable_cards",
+]
+
+#: The packaged-skill manifest filename (compared case-sensitively).
+SKILL_MANIFEST: Final[str] = "SKILL.md"
+
+#: Directory names the walk never descends into.
+PRUNED_DIRS: Final[frozenset[str]] = frozenset({"node_modules", ".git"})
+
+#: The frontmatter keys this loader understands. A key outside this set marks
+#: the document as malformed — the format is closed, so a stray key is far
+#: more likely a typo than an intentional extension.
+KNOWN_FRONTMATTER_KEYS: Final[frozenset[str]] = frozenset(
+    {
+        "name",
+        "description",
+        "license",
+        "compatibility",
+        "metadata",
+        "allowed-tools",
+        "disable-model-invocation",
+    }
+)
+
+#: The Agent-Skills naming rule: lowercase ASCII words joined by single
+#: hyphens.
+_NAME_PATTERN: Final[re.Pattern[str]] = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _Candidate:
+    """One file the walk has identified as a skill candidate."""
+
+    # Absolute path of the candidate markdown file.
+    path: str
+    # The name the file's enclosing directory implies (for packaged skills).
+    dir_name: str
+
+
+def _walk_candidates(root: str, seen: set[str]) -> Iterator[_Candidate]:
+    """Walk a root directory, yielding every skill candidate beneath it.
+
+    Generator-driven so the validation stage can consume candidates lazily. At
+    the root the walk treats direct ``*.md`` files as single-file skills; in
+    every subdirectory it treats a ``SKILL.md`` as a packaged skill. Dotfiles,
+    dot-dirs, and the pruned directory set are skipped, and physical paths are
+    not revisited (symlink loops and shared targets resolve to one realpath).
+
+    :param root: the directory to walk
+    :param seen: realpaths already visited, to break symlink cycles
+    """
+    yield from _walk_level(root, True, seen)
+
+
+def _walk_level(directory: str, at_root: bool, seen: set[str]) -> Iterator[_Candidate]:
+    """Recursive level walk. ``at_root`` distinguishes the top level (where
+    loose ``*.md`` files count) from nested levels (where only ``SKILL.md``
+    counts)."""
+    try:
+        entries = sorted(os.listdir(directory))
+    except OSError:
+        return
+
+    for entry in entries:
+        if entry.startswith("."):
+            continue
+        full = os.path.join(directory, entry)
+
+        try:
+            stats = os.stat(full)  # follows symlinks
+        except OSError:
+            continue
+
+        if _stat.S_ISDIR(stats.st_mode):
+            if entry in PRUNED_DIRS:
+                continue
+            try:
+                real = os.path.realpath(full, strict=True)
+            except OSError:
+                continue
+            if real in seen:
+                continue
+            seen.add(real)
+            yield from _walk_level(full, False, seen)
+            continue
+
+        if not _stat.S_ISREG(stats.st_mode):
+            continue
+
+        if at_root:
+            if entry.lower().endswith(".md"):
+                yield _Candidate(path=full, dir_name=os.path.basename(os.path.dirname(full)))
+        elif entry == SKILL_MANIFEST:
+            yield _Candidate(path=full, dir_name=os.path.basename(os.path.dirname(full)))
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+# A validation step's verdict: either a problem string or ``None`` for "ok".
+
+
+def _check_name(name: str, dir_name: str, from_dir: bool) -> str | None:
+    """Validate a skill name against the Agent-Skills naming rule: lowercase
+    ASCII letters, digits, and single internal hyphens, no longer than the
+    format limit, and — for packaged skills — matching the enclosing
+    directory.
+
+    :param name: the candidate name (from frontmatter or the directory)
+    :param dir_name: the enclosing directory's name, for the match check
+    :param from_dir: whether the name was inferred from the directory (skips
+        the match check, which would be trivially true)
+    :returns: a problem description, or ``None`` when the name is valid
+    """
+    if not name:
+        return "a skill must declare a non-empty name"
+    if len(name) > SKILL_NAME_LIMIT:
+        return f"the name exceeds the {SKILL_NAME_LIMIT}-character limit"
+    if _NAME_PATTERN.fullmatch(name) is None:
+        return "the name must be lowercase words joined by single hyphens"
+    if not from_dir and name != dir_name:
+        return f'the declared name "{name}" does not match its directory "{dir_name}"'
+    return None
+
+
+def _check_description(description: str) -> str | None:
+    """Validate a description: present and within the format's length limit.
+
+    :param description: the candidate description
+    :returns: a problem description, or ``None`` when valid
+    """
+    if not description:
+        return "a skill must declare a description so the model can gate it"
+    if len(description) > SKILL_DESCRIPTION_LIMIT:
+        return f"the description exceeds the {SKILL_DESCRIPTION_LIMIT}-character limit"
+    return None
+
+
+def _check_frontmatter_keys(frontmatter: Mapping[str, object]) -> str | None:
+    """Validate the frontmatter's key set: every key must be one the format
+    defines.
+
+    :param frontmatter: the raw parsed frontmatter map
+    :returns: a problem description naming the first stray key, or ``None``
+    """
+    for key in frontmatter:
+        if key not in KNOWN_FRONTMATTER_KEYS:
+            return f'unrecognised frontmatter key "{key}"'
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Frontmatter projection
+# ---------------------------------------------------------------------------
+
+
+def _project_frontmatter(raw: Mapping[str, object]) -> SkillFrontmatter:
+    """Project a raw frontmatter map onto the typed
+    :class:`~induscode.briefing.contract.SkillFrontmatter`.
+
+    Translates the format's kebab-case keys (``allowed-tools``,
+    ``disable-model-invocation``) to the snake_case fields, parses the tool
+    list from a comma-or-whitespace-separated scalar, and coerces the
+    invocation flag. Keys the projection does not name are dropped (the
+    key-set check has already vetted them).
+    """
+    kwargs: dict[str, object] = {}
+
+    name = raw.get("name")
+    if isinstance(name, str):
+        kwargs["name"] = name.strip()
+    description = raw.get("description")
+    if isinstance(description, str):
+        kwargs["description"] = description.strip()
+    license_tag = raw.get("license")
+    if isinstance(license_tag, str):
+        kwargs["license"] = license_tag.strip()
+    compatibility = raw.get("compatibility")
+    if isinstance(compatibility, str):
+        kwargs["compatibility"] = compatibility.strip()
+
+    metadata = raw.get("metadata")
+    if isinstance(metadata, Mapping):
+        kwargs["metadata"] = metadata
+
+    tools = raw.get("allowed-tools")
+    if isinstance(tools, str):
+        items = tuple(t.strip() for t in re.split(r"[\s,]+", tools) if t.strip())
+        if items:
+            kwargs["allowed_tools"] = items
+    elif isinstance(tools, (list, tuple)):
+        kwargs["allowed_tools"] = tuple(str(t) for t in tools)
+
+    flag = raw.get("disable-model-invocation")
+    if flag is True or flag == "true":
+        kwargs["disable_model_invocation"] = True
+
+    return SkillFrontmatter(**kwargs)  # type: ignore[arg-type]
+
+
+# ---------------------------------------------------------------------------
+# Parsing one candidate
+# ---------------------------------------------------------------------------
+
+
+def _diag(kind: SkillOutcomeKind, location: str, detail: str) -> SkillDiagnostic:
+    """Build a diagnostic record."""
+    return SkillDiagnostic(kind=kind, location=location, detail=detail)
+
+
+def _parse_candidate(
+    candidate: _Candidate, origin: MacroOrigin
+) -> tuple[SkillCard | None, SkillDiagnostic]:
+    """Read and validate one candidate file into a
+    :class:`~induscode.briefing.contract.SkillCard` (or a failure diagnostic).
+    Never raises: an unreadable file becomes an ``invalid`` diagnostic.
+
+    :param candidate: the file to parse
+    :param origin: where the candidate's root was classified
+    :returns: the parsed card (or ``None``) plus its diagnostic
+    """
+    path, dir_name = candidate.path, candidate.dir_name
+
+    try:
+        text = Path(path).read_text(encoding="utf-8")
+    except Exception as cause:
+        detail = f"could not read the skill file ({_describe_cause(cause)})"
+        return None, _diag("invalid", path, detail)
+
+    split = split_frontmatter(text)
+
+    key_problem = _check_frontmatter_keys(split.frontmatter)
+    if key_problem is not None:
+        return None, _diag("invalid", path, key_problem)
+
+    fm = _project_frontmatter(split.frontmatter)
+
+    declared_name = fm.name or ""
+    from_dir = not declared_name
+    name = dir_name if from_dir else declared_name
+    name_problem = _check_name(name, dir_name, from_dir)
+    if name_problem is not None:
+        return None, _diag("invalid", path, name_problem)
+
+    description = fm.description or ""
+    desc_problem = _check_description(description)
+    if desc_problem is not None:
+        return None, _diag("invalid", path, desc_problem)
+
+    card = SkillCard(
+        name=name,
+        description=description,
+        body=split.body,
+        location=path,
+        origin=origin,
+        frontmatter=fm,
+    )
+    return card, _diag("loaded", path, f'loaded skill "{name}"')
+
+
+def _describe_cause(cause: object) -> str:
+    """Render a caught value into a short human phrase for a diagnostic."""
+    return str(cause)
+
+
+# ---------------------------------------------------------------------------
+# Aggregation
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SkillRoot:
+    """One root directory to load skill cards from, with its origin tag."""
+
+    # The directory to walk.
+    dir: str
+    # How cards discovered under this root are tagged.
+    origin: MacroOrigin
+
+
+def load_skill_cards(
+    directory: str | os.PathLike[str], origin: MacroOrigin = "path"
+) -> SkillLoad:
+    """Load and validate the capability cards under one directory root.
+
+    Walks the root for candidates, parses each, and accumulates the
+    diagnostics. Name deduplication is *not* applied here (a single root
+    rarely collides with itself in a way worth reporting); use
+    :func:`gather_skill_cards` to merge several roots with collision
+    reporting. Symlink cycles within the root are broken by realpath tracking.
+
+    :param directory: the root directory to scan
+    :param origin: the origin tag for cards found here
+    :returns: the cards and diagnostics produced from this root
+    """
+    cards: list[SkillCard] = []
+    diagnostics: list[SkillDiagnostic] = []
+    seen: set[str] = set()
+
+    for candidate in _walk_candidates(os.fspath(directory), seen):
+        card, diagnostic = _parse_candidate(candidate, origin)
+        diagnostics.append(diagnostic)
+        if card is not None:
+            cards.append(card)
+
+    return SkillLoad(cards=tuple(cards), diagnostics=tuple(diagnostics))
+
+
+def gather_skill_cards(roots: Sequence[SkillRoot]) -> SkillLoad:
+    """Load and merge capability cards from several roots, deduping by name.
+
+    Roots are processed in order; the first card to claim a name wins, and any
+    later card with the same name is dropped with a ``collision`` diagnostic
+    (its own per-root ``loaded`` line is rewritten to the collision outcome).
+    The merged card list is the deduped survivors, in discovery order.
+
+    :param roots: the roots to load, in precedence order (earliest wins)
+    :returns: the merged cards and the combined diagnostic stream
+    """
+    cards: list[SkillCard] = []
+    diagnostics: list[SkillDiagnostic] = []
+    claimed: dict[str, str] = {}  # name → winning location
+
+    for root in roots:
+        loaded = load_skill_cards(root.dir, root.origin)
+        for d in loaded.diagnostics:
+            if d.kind != "loaded":
+                diagnostics.append(d)
+            # `loaded` diagnostics are re-emitted below alongside the card so
+            # a collision can rewrite them; non-loaded ones pass through
+            # as-is.
+        for card in loaded.cards:
+            winner = claimed.get(card.name)
+            if winner is not None:
+                diagnostics.append(
+                    _diag(
+                        "collision",
+                        card.location,
+                        f'the name "{card.name}" was already claimed by {winner}; '
+                        "this card is dropped",
+                    )
+                )
+                continue
+            claimed[card.name] = card.location
+            cards.append(card)
+            diagnostics.append(_diag("loaded", card.location, f'loaded skill "{card.name}"'))
+
+    return SkillLoad(cards=tuple(cards), diagnostics=tuple(diagnostics))
+
+
+def model_invocable_cards(cards: Sequence[SkillCard]) -> list[SkillCard]:
+    """Filter cards down to those the model may auto-invoke (i.e. that are not
+    marked ``disable-model-invocation``). The hidden cards remain available as
+    explicit commands but do not appear in the briefing's skill block.
+
+    :param cards: the full card set
+    :returns: the subset eligible for model invocation
+    """
+    return [c for c in cards if c.frontmatter.disable_model_invocation is not True]

induscode/capability_deck/__init__.py

@@ -0,0 +1,233 @@
+"""Capability-deck subsystem — public barrel.
+
+Re-exports the FROZEN tooling-layer contract: the :data:`Capability` alias
+over the framework ``AgentTool``, the branded :data:`CapabilityId`, the
+catalog row (:class:`CapabilityCard`) that is the deck's single source of
+truth, the :data:`DeckProfile` table and :class:`DeckContext` injection bag,
+the event-sourced MCP enrollment model (:class:`BridgeEntry`,
+:data:`BridgeOp`, :class:`LedgerSnapshot` + the pure :func:`reduce_ledger`
+fold), the assembled :class:`ToolDeck` the conductor consumes, and the typed
+:class:`DeckFault` — plus every behavior module:
+
+- the **builtin bridge** — the single seam re-exposing the framework's native
+  tools (read/write/edit/ls/grep/find/bash/process/checklist/web) as
+  capabilities, one 12-row descriptor table;
+- the **manifest catalog** — the single ``CAPABILITY_CARDS`` source of truth
+  plus the lookups/profile filters derived from it;
+- the **app-novel cards** — the in-house tools the deck builds itself
+  (checklist, background-process proxy, delegate/sub-agent, SaaS connector,
+  working memory) plus their builders, stores, and injection-handle keys;
+- the **bridge ledger** — content-hash / ULID key minting, the immutable
+  :class:`BridgeLedger` with its pure enroll/retire/withdraw transitions and
+  live projections, and the side-effecting mount/adapt/detach network
+  operations;
+- **deck provisioning** — the single data-driven :func:`provision_deck`
+  assembler over the (inversion-preserving) profile table, plus the
+  profile-to-cards selection it walks.
+
+Consumers import the deck surface from ``induscode.capability_deck`` rather
+than reaching into individual modules.
+"""
+
+from __future__ import annotations
+
+from .bridge_ledger import (
+    AttachResult,
+    BridgeLedger,
+    EnrollRequest,
+    attach_bridge_capabilities,
+    bridge_box_to_capabilities,
+    bridge_capability_card,
+    bridge_config,
+    bridge_content_key,
+    bridge_ledger_from_log,
+    bridge_ulid_key,
+    detach_bridge,
+    empty_bridge_ledger,
+    enroll_bridge_card,
+    live_capabilities,
+    live_capabilities_for_server,
+    qualify_bridge_name,
+    retire,
+    withdraw_server,
+)
+from .builtin_bridge import (
+    BUILTIN_BRIDGE,
+    BUILTIN_IDS,
+    BUILTIN_PROFILES,
+    BridgeBuilder,
+    BuiltinDescriptor,
+    build_builtin,
+    build_builtins_for_profile,
+    builtin_descriptors,
+)
+from .cards import (
+    APP_NOVEL_CARDS,
+    DELEGATE_HANDLE_KEY,
+    DaemonDetails,
+    DaemonState,
+    DaemonTable,
+    DelegateRequest,
+    DelegateResult,
+    DelegateRunner,
+    InMemoryStore,
+    MEMORY_HANDLE_KEY,
+    MemoryDetails,
+    MemoryStore,
+    RemoteExecution,
+    RemoteToolSummary,
+    SAAS_GATEWAY_KEY,
+    SaasDetails,
+    SaasGatewayPort,
+    TaskDetails,
+    TodoDetails,
+    TodoItem,
+    TodoLedger,
+    TodoState,
+    TodoWeight,
+    build_daemon_capability,
+    build_memory_capability,
+    build_saas_capability,
+    build_task_capability,
+    build_todo_capability,
+    daemon_card,
+    memory_card,
+    saas_card,
+    task_card,
+    todo_card,
+)
+from .contract import (
+    AgentTool,
+    AgentToolResult,
+    AnyCapability,
+    BridgeEntry,
+    BridgeKey,
+    BridgeOp,
+    Capability,
+    CapabilityCard,
+    CapabilityId,
+    CardProfiles,
+    DeckBox,
+    DeckContext,
+    DeckFault,
+    DeckFaultKind,
+    DeckFrameworkHandles,
+    DeckFsBackend,
+    DeckProfile,
+    DeckShellBackend,
+    LedgerSnapshot,
+    Schema,
+    ToolBox,
+    ToolDeck,
+    bridge_key,
+    capability_id,
+    deck_fault,
+    reduce_ledger,
+)
+from .manifest import (
+    CAPABILITY_CARDS,
+    CAPABILITY_INDEX,
+    CARD_PROFILES,
+    capability_ids,
+    cards_for_profile,
+    find_card,
+    has_capability,
+)
+from .provision import cards_for_deck_profile, provision_deck
+
+__all__ = [
+    "APP_NOVEL_CARDS",
+    "AgentTool",
+    "AgentToolResult",
+    "AnyCapability",
+    "AttachResult",
+    "BUILTIN_BRIDGE",
+    "BUILTIN_IDS",
+    "BUILTIN_PROFILES",
+    "BridgeBuilder",
+    "BridgeEntry",
+    "BridgeKey",
+    "BridgeLedger",
+    "BridgeOp",
+    "BuiltinDescriptor",
+    "CAPABILITY_CARDS",
+    "CAPABILITY_INDEX",
+    "CARD_PROFILES",
+    "Capability",
+    "CapabilityCard",
+    "CapabilityId",
+    "CardProfiles",
+    "DELEGATE_HANDLE_KEY",
+    "DaemonDetails",
+    "DaemonState",
+    "DaemonTable",
+    "DeckBox",
+    "DeckContext",
+    "DeckFault",
+    "DeckFaultKind",
+    "DeckFrameworkHandles",
+    "DeckFsBackend",
+    "DeckProfile",
+    "DeckShellBackend",
+    "DelegateRequest",
+    "DelegateResult",
+    "DelegateRunner",
+    "EnrollRequest",
+    "InMemoryStore",
+    "LedgerSnapshot",
+    "MEMORY_HANDLE_KEY",
+    "MemoryDetails",
+    "MemoryStore",
+    "RemoteExecution",
+    "RemoteToolSummary",
+    "SAAS_GATEWAY_KEY",
+    "SaasDetails",
+    "SaasGatewayPort",
+    "Schema",
+    "TaskDetails",
+    "TodoDetails",
+    "TodoItem",
+    "TodoLedger",
+    "TodoState",
+    "TodoWeight",
+    "ToolBox",
+    "ToolDeck",
+    "attach_bridge_capabilities",
+    "bridge_box_to_capabilities",
+    "bridge_capability_card",
+    "bridge_config",
+    "bridge_content_key",
+    "bridge_key",
+    "bridge_ledger_from_log",
+    "bridge_ulid_key",
+    "build_builtin",
+    "build_builtins_for_profile",
+    "build_daemon_capability",
+    "build_memory_capability",
+    "build_saas_capability",
+    "build_task_capability",
+    "build_todo_capability",
+    "builtin_descriptors",
+    "capability_id",
+    "capability_ids",
+    "cards_for_deck_profile",
+    "cards_for_profile",
+    "daemon_card",
+    "deck_fault",
+    "detach_bridge",
+    "empty_bridge_ledger",
+    "enroll_bridge_card",
+    "find_card",
+    "has_capability",
+    "live_capabilities",
+    "live_capabilities_for_server",
+    "memory_card",
+    "provision_deck",
+    "qualify_bridge_name",
+    "reduce_ledger",
+    "retire",
+    "saas_card",
+    "task_card",
+    "todo_card",
+    "withdraw_server",
+]