induscode 0.1.0__py3-none-any.whl

induscode/capability_deck/contract.py

@@ -0,0 +1,450 @@
+"""Capability-deck contract — the FROZEN type surface of the tooling layer.
+
+This module is the single typed seam between the coding-agent *product* and
+the set of callable capabilities the agent runtime executes — file ops, the
+shell, search, the web, the delegate/subagent action, the checklist, the
+background-process proxy, SaaS connector actions, and dynamically-grafted MCP
+server tools. It declares *only* shapes plus a handful of tiny inert helpers
+(an id brand, a key minter, a fault factory, and a pure ledger reducer) — no
+I/O, no provisioning, no orchestration. Every later deck module (the manifest
+catalog, the builtin bridge, the per-concern provisioners, the bridge network,
+and the assembled :class:`ToolDeck`) is written against the names declared
+here, so the file is intentionally small, append-mostly, and stable.
+
+Design stance (ported from TS ``src/capability-deck/contract.ts``):
+
+- A :data:`Capability` is exactly the framework ``AgentTool`` shape. The deck
+  does not invent a parallel descriptor type; it *manages* AgentTools so the
+  conductor can consume the deck's output directly as ``options.tools``.
+- The catalog is a single source of truth: :class:`CapabilityCard` rows live
+  in one ``CAPABILITY_CARDS`` tuple (built by the manifest module), and every
+  index/lookup is derived *from* that tuple rather than hand-maintained in a
+  second parallel map.
+- Profiles replace a trio of near-identical build functions: one data-driven
+  provisioner walks a :data:`DeckProfile` (``"authoring"`` | ``"survey"`` |
+  ``"all"``) to assemble the right capability set for a session.
+- MCP enrollment is **event-sourced**: a ``BridgeLedger`` is the fold of an
+  append-only stream of :class:`BridgeEntry` events (``enroll`` / ``retire``),
+  keyed by a content-hash / ULID :data:`BridgeKey` rather than a path digest.
+  The current view is a :class:`LedgerSnapshot` reduced from that stream.
+
+Port note — TypeBox collapses to plain JSON-schema mappings
+-----------------------------------------------------------
+The TS contract re-exported ``TSchema`` / ``Static`` from ``@sinclair/typebox``
+and parameterized ``Capability<TParameters, TDetails>`` over them. The Python
+framework's ``AgentTool`` Protocol carries ``parameters`` as a plain
+JSON-schema ``Mapping`` and is not generic, so:
+
+- :data:`Schema` is the stand-in for ``TSchema`` (a JSON-schema mapping);
+- ``Static`` (a compile-time type computation) has no Python analogue and is
+  dropped — runtime guards replace it where the cards need required fields;
+- :data:`Capability` and :data:`AnyCapability` both alias ``AgentTool``
+  (the "erased" and "open" forms collapse to one structural Protocol).
+
+Framework anchors (all from the ``indusagi`` package — the sibling rebuilt
+framework this app targets):
+
+- :class:`AgentTool`, :class:`AgentToolResult` ← ``indusagi.agent``
+- :class:`ToolBox` ← ``indusagi.runtime``
+
+The deck never re-declares these; it composes them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Literal, NewType, Protocol, TypeAlias
+
+from indusagi.agent import AgentTool, AgentToolResult
+from indusagi.runtime import ToolBox
+
+__all__ = [
+    "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",
+]
+
+
+# ---------------------------------------------------------------------------
+# Capability
+# ---------------------------------------------------------------------------
+
+#: A JSON-schema parameter shape — the Python stand-in for TypeBox ``TSchema``.
+#:
+#: The framework's tools carry their parameter schemas as plain mappings; the
+#: deck threads them (into content keys, into the model's tool listing) but
+#: never interprets them.
+Schema: TypeAlias = Mapping[str, Any]
+
+#: A single callable tool the deck manages.
+#:
+#: Deliberately an alias of the framework ``AgentTool`` rather than a fresh
+#: shape: the conductor and the framework agent loop both expect ``AgentTool``
+#: objects, so the deck's whole job is to *assemble* them, not to wrap them in
+#: a parallel descriptor. A ``Capability`` therefore carries the framework
+#: contract verbatim — ``name``, ``label``, ``description``, a JSON-schema
+#: ``parameters`` mapping, and an async ``execute`` — while the deck owns only
+#: the catalog, profiles, and dynamic-bridge layers around it.
+Capability: TypeAlias = AgentTool
+
+#: A capability whose parameter/detail types are erased — the element type of
+#: a heterogeneous deck.
+#:
+#: In TS this was ``Capability<TSchema, unknown>``; the Python ``AgentTool``
+#: Protocol is structural and ungeneric, so the open and erased forms collapse
+#: to the same alias. Kept as its own name so deck code reads identically to
+#: the TS lineage (``AnyCapability`` lists are what the conductor consumes as
+#: ``options.tools`` and what :meth:`ToolDeck.tools` / :meth:`ToolDeck.box`
+#: surface).
+AnyCapability: TypeAlias = AgentTool
+
+#: String-branded stable identifier for a capability.
+#:
+#: The wire-facing tool ``name`` the model sees (e.g. ``"read"``, ``"bash"``,
+#: ``"composio_execute"``, a qualified ``"<server>__<tool>"``); branded so an
+#: arbitrary string cannot be passed where a vetted capability id is required.
+#: Mint one with :func:`capability_id`.
+CapabilityId = NewType("CapabilityId", str)
+
+
+def capability_id(raw: str) -> CapabilityId:
+    """Brand a raw string as a :data:`CapabilityId`. The single sanctioned way
+    to produce one, so id provenance stays uniform across the catalog and
+    bridge.
+
+    :param raw: the wire-facing tool name to brand
+    """
+    return CapabilityId(raw)
+
+
+# ---------------------------------------------------------------------------
+# Catalog
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CapabilityCard:
+    """One row of the static capability catalog — the deck's single source of
+    truth.
+
+    A card is *metadata plus a builder*: it advertises the capability's
+    identity (``id``, ``title``, ``summary``) for help/introspection and
+    slash-command listings, and carries a :attr:`build` factory that mints the
+    live :data:`Capability` for a given :class:`DeckContext`. The catalog
+    tuple (``CAPABILITY_CARDS``, owned by the manifest module) is the only
+    hand-maintained list; every index, profile membership, and lookup is
+    derived from it.
+
+    ``build`` is pure with respect to the deck: it reads the injected backends
+    from the context and returns a configured :data:`Capability`; it performs
+    no enrollment and mutates no shared state.
+    """
+
+    # Stable, wire-facing identifier of the capability this card builds.
+    id: CapabilityId
+    # Short human-facing title for catalogs and help text.
+    title: str
+    # One-line description of what the capability does, in the deck's own voice.
+    summary: str
+    # Build the live capability for a working context (pure).
+    build: Callable[[DeckContext], Capability]
+
+
+#: The set of capabilities a card is eligible for, by profile.
+#:
+#: A card declares which :data:`DeckProfile` values it participates in; the
+#: data-driven provisioner intersects this with the requested profile instead
+#: of branching through separate per-profile build functions. ``"all"`` is
+#: implied for every card and need not be listed.
+CardProfiles: TypeAlias = Sequence["DeckProfile"]
+
+
+# ---------------------------------------------------------------------------
+# Profiles & context
+# ---------------------------------------------------------------------------
+
+#: The named capability sets a session can be provisioned with — the profile
+#: table that replaces a trio of near-identical build functions.
+#:
+#: - ``authoring`` — the full mutating set: read/write/edit/ls + search +
+#:   shell + web + checklist + delegate + background processes + SaaS actions.
+#:   The default for an interactive coding session.
+#: - ``survey``    — observe-only: read/ls/search/web/checklist. No filesystem
+#:   mutation and no shell. Safe when the agent must not change the workspace.
+#: - ``all``       — every registered capability, nothing withheld.
+DeckProfile: TypeAlias = Literal["authoring", "survey", "all"]
+
+#: Filesystem backend port a capability may bind to.
+#:
+#: Intentionally opaque at the contract layer: the concrete port shape is
+#: owned by the framework capabilities kernel. The deck only needs to *thread*
+#: it from a host into a card's builder, so the contract treats it as a
+#: branded handle — threaded, not interpreted, here.
+DeckFsBackend = NewType("DeckFsBackend", object)
+
+#: Shell backend port a capability may bind to. Opaque for the same reason as
+#: :data:`DeckFsBackend`: a branded handle the contract threads but never
+#: reads.
+DeckShellBackend = NewType("DeckShellBackend", object)
+
+#: A bag of opaque framework handles the novel capabilities wire to — the
+#: subagent/delegate manager, the checklist ledger, the background-process
+#: controller, the SaaS gateway. Each is optional and keyed by name; a card
+#: that needs one reads it from here, and the manifest fills in defaults.
+DeckFrameworkHandles: TypeAlias = Mapping[str, object]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DeckContext:
+    """The working context handed to :attr:`CapabilityCard.build`.
+
+    Bundles the workspace root with the injectable backends a capability binds
+    to, so capabilities stay framework-agnostic and testable: a test passes
+    fake ``fs`` / ``shell`` ports, production passes the framework-backed
+    ones. Every field beyond ``cwd`` is optional — the manifest supplies
+    framework defaults when a backend is not injected.
+    """
+
+    # Absolute working directory the session's capabilities are scoped to.
+    cwd: str
+    # Injectable filesystem port; framework backend is the default.
+    fs: DeckFsBackend | None = None
+    # Injectable shell port; framework backend is the default.
+    shell: DeckShellBackend | None = None
+    # Opaque framework handles a capability may need (model registry, stores).
+    framework: DeckFrameworkHandles | None = None
+
+
+# ---------------------------------------------------------------------------
+# Bridge ledger (event-sourced MCP enrollment)
+# ---------------------------------------------------------------------------
+
+#: The stable key of an enrolled bridge capability.
+#:
+#: Minted from the capability's identity rather than from a working-directory
+#: digest, so the same external tool grafted from two sessions collapses to
+#: one key and re-enrolling is idempotent. In practice a content hash of the
+#: qualified ``<server>__<tool>`` name (and its schema) or a fresh ULID;
+#: branded so a raw string cannot stand in for a vetted key.
+BridgeKey = NewType("BridgeKey", str)
+
+
+def bridge_key(raw: str) -> BridgeKey:
+    """Brand a raw string as a :data:`BridgeKey`."""
+    return BridgeKey(raw)
+
+
+#: The operations the MCP enrollment stream records.
+#:
+#: - ``enroll`` — a bridge capability became available and was grafted in (an
+#:   upsert: re-enrolling the same :data:`BridgeKey` replaces its entry).
+#: - ``retire`` — a bridge capability (or a whole server's set) was withdrawn
+#:   (a splice: the keyed entry is removed from the reduced view).
+BridgeOp: TypeAlias = Literal["enroll", "retire"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BridgeEntry:
+    """A single append-only event in the MCP enrollment stream.
+
+    The ledger is never mutated in place; every change is one of these entries
+    appended to an ordered log, and the live view is the fold of that log. An
+    ``enroll`` entry carries the grafted :data:`Capability` and the owning
+    server; a ``retire`` entry need only name the :data:`BridgeKey` (and
+    server) to remove. Field names are the deck's own, not the framework's
+    registry schema.
+    """
+
+    # The operation this event records.
+    op: BridgeOp
+    # Stable key of the bridge capability the event concerns.
+    key: BridgeKey
+    # Id of the external MCP server that owns the capability.
+    server: str
+    # The grafted capability — present on `enroll`, omitted on `retire`.
+    capability: AnyCapability | None = None
+    # Monotonic sequence number; the append order, used to break upsert ties.
+    seq: int
+    # ISO-8601 timestamp the event was appended.
+    at: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class LedgerSnapshot:
+    """The reduced, current view of the MCP enrollment ledger.
+
+    A pure projection of the :class:`BridgeEntry` stream: the set of bridge
+    capabilities live *right now*, keyed by :data:`BridgeKey`, alongside the
+    highest sequence number folded and a per-server tool count for status
+    rendering. Produced by :func:`reduce_ledger`; consumers read it, never
+    mutate (both mappings are read-only proxies).
+    """
+
+    # Currently-enrolled bridge capabilities, keyed by their stable key.
+    live: Mapping[BridgeKey, AnyCapability]
+    # Number of live capabilities grafted from each server, keyed by server id.
+    by_server: Mapping[str, int]
+    # The highest `BridgeEntry.seq` folded into this snapshot.
+    high_water: int
+
+
+def reduce_ledger(entries: Sequence[BridgeEntry]) -> LedgerSnapshot:
+    """Fold an append-only :class:`BridgeEntry` stream into its current
+    :class:`LedgerSnapshot`.
+
+    Pure and total: ``enroll`` upserts the keyed capability (later ``seq``
+    wins on a repeated key), ``retire`` removes it, and entries are applied in
+    ``seq`` order so the result is independent of input order. This is the
+    single sanctioned reducer, so the event-sourced view stays consistent
+    across every producer.
+
+    :param entries: the enrollment events to fold, in any order
+    """
+    ordered = sorted(entries, key=lambda entry: entry.seq)
+    live: dict[BridgeKey, AnyCapability] = {}
+    high_water = 0
+    for entry in ordered:
+        if entry.seq > high_water:
+            high_water = entry.seq
+        if entry.op == "enroll":
+            if entry.capability is not None:
+                live[entry.key] = entry.capability
+        else:
+            live.pop(entry.key, None)
+    # Per-server counts are derived from the live set: map each live key back
+    # to the server that last touched it, then tally one per live key.
+    key_server: dict[BridgeKey, str] = {}
+    for entry in ordered:
+        key_server[entry.key] = entry.server
+    by_server: dict[str, int] = {}
+    for key in live:
+        server = key_server.get(key)
+        if server is None:
+            continue
+        by_server[server] = by_server.get(server, 0) + 1
+    return LedgerSnapshot(
+        live=MappingProxyType(live),
+        by_server=MappingProxyType(by_server),
+        high_water=high_water,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tool deck
+# ---------------------------------------------------------------------------
+
+
+class ToolDeck(Protocol):
+    """The assembled capability deck a session runs against.
+
+    The product of provisioning a :data:`DeckProfile` against a
+    :class:`DeckContext`, optionally with bridge capabilities grafted on. It
+    exposes exactly two reads: the flat capability list (for inspection,
+    naming, and ``--tools`` style selection) and the consumable box the
+    conductor wires in.
+
+    :meth:`box` returns a ``list[AnyCapability]`` — the same ``AgentTool``
+    list the conductor's session options accept directly — so a deck drops
+    straight into ``SessionConductorOptions.tools``. The :data:`DeckBox` alias
+    also admits the framework ``ToolBox`` for hosts that drive the lower-level
+    runtime contract instead of the conductor.
+    """
+
+    def tools(self) -> list[AnyCapability]:
+        """The flat list of live capabilities, for inspection and selection."""
+        ...
+
+    def box(self) -> DeckBox:
+        """The consumable surface the conductor (or runtime) wires in as its
+        tools."""
+        ...
+
+
+#: What :meth:`ToolDeck.box` hands to a consumer.
+#:
+#: Primarily a ``list[AnyCapability]`` (= ``AgentTool`` list), which the
+#: conductor accepts verbatim as ``options.tools``. Also admits the framework
+#: :class:`ToolBox` so a host wiring the raw runtime contract — or grafting
+#: MCP tools through the protocol bridge, which yields a ``ToolBox`` — can
+#: consume the deck the same way.
+DeckBox: TypeAlias = "list[AnyCapability] | ToolBox"
+
+
+# ---------------------------------------------------------------------------
+# Deck faults
+# ---------------------------------------------------------------------------
+
+#: The closed set of failure categories the deck can surface during
+#: provisioning or bridge enrollment.
+#:
+#: - ``unknown_capability`` — a requested id is not in the catalog.
+#: - ``build_failed``       — a card's ``build`` threw while minting a
+#:   capability.
+#: - ``bridge``             — connecting/listing/grafting an MCP server
+#:   failed.
+#: - ``backend``            — a required injected backend was missing or
+#:   invalid.
+DeckFaultKind: TypeAlias = Literal["unknown_capability", "build_failed", "bridge", "backend"]
+
+
+class DeckFault(Exception):
+    """A typed, discriminated failure raised by the deck.
+
+    ``kind`` selects the category; ``message`` is a human-readable summary;
+    the optional ``cause`` carries the underlying error for logging without
+    forcing consumers to parse the message. Construct one with
+    :func:`deck_fault`.
+
+    Port note: the TS shape was a plain frozen record ``throw``-n as a value;
+    Python requires raisables to be exceptions, so the same three fields ride
+    on an :class:`Exception` subclass.
+    """
+
+    def __init__(
+        self, kind: DeckFaultKind, message: str, cause: object | None = None
+    ) -> None:
+        super().__init__(message)
+        # Failure category — the discriminant consumers switch on.
+        self.kind: DeckFaultKind = kind
+        # Human-readable, single-line summary of what went wrong.
+        self.message: str = message
+        # Underlying error or structured detail, if any.
+        self.cause: object | None = cause
+
+
+def deck_fault(
+    kind: DeckFaultKind, message: str, cause: object | None = None
+) -> DeckFault:
+    """Construct a :class:`DeckFault`. The single sanctioned way to mint one,
+    so the shape stays uniform across every producer.
+
+    :param kind: the failure category
+    :param message: a human-readable, single-line summary
+    :param cause: optional underlying error or structured detail
+    """
+    return DeckFault(kind, message, cause)

induscode/capability_deck/manifest.py

@@ -0,0 +1,126 @@
+"""Capability catalog — the deck's single source of truth.
+
+This module owns :data:`CAPABILITY_CARDS`: the one hand-maintained-in-one-place
+tuple of :class:`CapabilityCard` rows the rest of the deck reads from. Every
+index, lookup, and profile-membership query is *derived* from this tuple, so
+there is never a second parallel map to keep in sync.
+
+The catalog is exactly the framework built-ins — read/write/edit/ls/grep/find/
+bash/process/the checklist pair/web search & fetch — projected out of the
+single :data:`BUILTIN_BRIDGE` table in :mod:`.builtin_bridge`. The app-novel
+cards (checklist, daemon proxy, delegate, SaaS actions, working memory) live
+in :mod:`.cards` and are concatenated onto the built-in selection by the
+provisioner's profile table, exactly as the TS lineage did.
+
+A :class:`CapabilityCard` is metadata plus a builder: the wire-facing id, the
+deck-side title/summary prose, and a ``build(ctx)`` that mints the live
+:data:`Capability`. The card does not carry profile membership — that lives in
+the profile table the provisioner consults — so the card shape stays the small
+catalog row the contract froze.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from .builtin_bridge import BuiltinDescriptor, builtin_descriptors
+from .contract import CapabilityCard, CapabilityId, CardProfiles, DeckProfile
+
+__all__ = [
+    "CAPABILITY_CARDS",
+    "CAPABILITY_INDEX",
+    "CARD_PROFILES",
+    "capability_ids",
+    "cards_for_profile",
+    "find_card",
+    "has_capability",
+]
+
+
+# ---------------------------------------------------------------------------
+# Card projection
+# ---------------------------------------------------------------------------
+
+
+def _card_of(descriptor: BuiltinDescriptor) -> CapabilityCard:
+    """Project one :class:`BuiltinDescriptor` into the contract's
+    :class:`CapabilityCard` shape — drop the profile membership (the
+    provisioner reads that from the profile table) and keep id, prose, and the
+    build closure."""
+    return CapabilityCard(
+        id=descriptor.id,
+        title=descriptor.title,
+        summary=descriptor.summary,
+        build=descriptor.build,
+    )
+
+
+# ---------------------------------------------------------------------------
+# The catalog
+# ---------------------------------------------------------------------------
+
+#: The static capability catalog — the deck's single source of truth.
+#:
+#: One ordered tuple of catalog rows, every row a framework built-in projected
+#: from the bridge table. Consumers never hand-build a parallel list — they
+#: read this tuple (or the derived :data:`CAPABILITY_INDEX` /
+#: :data:`CARD_PROFILES` below).
+CAPABILITY_CARDS: tuple[CapabilityCard, ...] = tuple(
+    _card_of(descriptor) for descriptor in builtin_descriptors()
+)
+
+#: The catalog keyed by wire-facing :data:`CapabilityId`, derived from
+#: :data:`CAPABILITY_CARDS`. Resolves a ``--tools name1,name2`` selection or a
+#: model-named tool to its card in O(1) without a second hand-maintained map.
+CAPABILITY_INDEX: Mapping[CapabilityId, CapabilityCard] = MappingProxyType(
+    {card.id: card for card in CAPABILITY_CARDS}
+)
+
+#: Profile membership for every catalog row, keyed by id and derived from the
+#: bridge table. The data-driven provisioner intersects this with a requested
+#: profile to assemble a session's capability set — no per-profile build
+#: functions, just a table walk.
+CARD_PROFILES: Mapping[CapabilityId, CardProfiles] = MappingProxyType(
+    {descriptor.id: descriptor.profiles for descriptor in builtin_descriptors()}
+)
+
+
+# ---------------------------------------------------------------------------
+# Derived lookups
+# ---------------------------------------------------------------------------
+
+
+def capability_ids() -> list[CapabilityId]:
+    """The wire-facing ids of every catalog row, in catalog order."""
+    return [card.id for card in CAPABILITY_CARDS]
+
+
+def has_capability(id: CapabilityId) -> bool:
+    """True when a catalog row exists under this id."""
+    return id in CAPABILITY_INDEX
+
+
+def find_card(id: CapabilityId) -> CapabilityCard | None:
+    """Fetch a catalog row by id, or ``None`` when the id is unknown."""
+    return CAPABILITY_INDEX.get(id)
+
+
+def cards_for_profile(profile: DeckProfile) -> list[CapabilityCard]:
+    """The catalog rows that participate in a profile, in catalog order.
+
+    ``all`` returns every row; a named profile keeps only the rows whose
+    membership (read from :data:`CARD_PROFILES`) admits it. The single place
+    profile filtering happens, so the provisioner stays a thin walk over this
+    result.
+
+    :param profile: the requested deck profile
+    """
+    if profile == "all":
+        return list(CAPABILITY_CARDS)
+    selected: list[CapabilityCard] = []
+    for card in CAPABILITY_CARDS:
+        profiles = CARD_PROFILES.get(card.id)
+        if profiles is not None and profile in profiles:
+            selected.append(card)
+    return selected