induscode 0.1.0__py3-none-any.whl

induscode/capability_deck/provision.py

@@ -0,0 +1,217 @@
+"""Deck provisioning — the single data-driven assembler.
+
+One function, :func:`provision_deck`, turns a :data:`DeckProfile` plus a
+:class:`DeckContext` into an assembled :class:`ToolDeck`. It replaces what
+would otherwise be a trio of near-identical ``build_authoring_tools`` /
+``build_survey_tools`` / ``build_all_tools`` functions with a single walk over
+a :data:`PROFILE_TABLE`-shaped policy mapping: the table says which catalog
+rows each profile draws from, the assembler builds exactly those rows against
+the context, and the result exposes the two reads the conductor needs —
+:meth:`ToolDeck.tools` (the flat capability list) and :meth:`ToolDeck.box`
+(the consumable ``AgentTool`` list it wires in as ``options.tools``).
+
+Why a table rather than three functions:
+
+- The catalog is already the single source of truth (``CAPABILITY_CARDS``
+  plus the app-novel cards). A profile is just a *selection policy* over that
+  catalog, so it is data — a small row per profile — not control flow.
+- Adding a profile, or moving a card between profiles, is a one-line table
+  edit with no new branch to keep in sync.
+
+Breadth runs ``authoring`` (narrowest, read-only) → ``survey`` (all
+built-ins) → ``all`` (built-ins + app cards), spelled out per profile below.
+
+The three profiles, in increasing breadth:
+
+- ``authoring`` — the read-only built-in subset: the observe-only tools the
+  framework exposes (read/ls/grep/find/web search & fetch/checklist-read). No
+  filesystem mutation, no shell, no app-novel cards. The safe selection for a
+  session that must inspect a workspace without changing it.
+- ``survey``    — the wider built-in subset: every framework built-in,
+  including the mutating ones (write/edit/bash/process/checklist-write).
+  Still no app-novel cards — just the full native tool set.
+- ``all``       — everything: every framework built-in plus every app-novel
+  card (the checklist, the background-process proxy, the delegate/sub-agent
+  action, the SaaS connector, working memory).
+
+The built-in catalog tags each native tool with the profiles it belongs to
+(``read`` etc. are observe-only; ``bash``/``write`` are mutating); this table
+maps the deck profiles onto those membership selections, so the
+read-only/wider split is a table lookup rather than a hand-maintained second
+tool list.
+
+.. warning:: **Profile-name inversion — ported verbatim** (plan §5 rule 5,
+   analysis 03 risk-1). The deck profile ``authoring`` maps to built-in
+   membership tag ``survey`` (the read-only subset) and the deck profile
+   ``survey`` maps to membership ``all``: a deck profile is a *selection
+   policy*, distinct from the per-tool membership tags the built-in catalog
+   carries, and the names deliberately do not line up. The
+   ``capability-deck`` test suite pins this exact semantics — do not
+   "intuitively" fix the table.
+
+Bridge (MCP) capabilities are *not* selected here — they are grafted at
+runtime through the bridge ledger and concatenated by the host onto a deck's
+:meth:`ToolDeck.tools`; provisioning only assembles the static catalog.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from .cards import APP_NOVEL_CARDS
+from .contract import (
+    AnyCapability,
+    CapabilityCard,
+    DeckBox,
+    DeckContext,
+    DeckProfile,
+    deck_fault,
+)
+from .manifest import cards_for_profile
+
+__all__ = [
+    "cards_for_deck_profile",
+    "provision_deck",
+]
+
+
+# ---------------------------------------------------------------------------
+# Profile table
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _ProfilePolicy:
+    """What card sources a profile draws from. The table is the policy; the
+    assembler is a thin walk over it. Each row is pure data — no build logic —
+    so a profile's breadth is declared in one place."""
+
+    # The built-in catalog *membership* this deck profile selects from
+    # (`cards_for_profile` reads it):
+    #   - "survey" — the observe-only built-ins (the read-only subset).
+    #   - "all"    — every built-in, mutating tools included (the wider set).
+    # The deck `authoring` profile maps to the read-only built-in membership
+    # and the deck `survey` profile to the full built-in set; the names differ
+    # because a deck profile is a *selection policy*, distinct from the
+    # per-tool membership tags the built-in catalog carries.
+    builtins: DeckProfile
+    # Whether the app-novel cards (checklist, background process, delegate,
+    # SaaS, memory) are included. Only the broadest profile grants the full set.
+    app_cards: bool
+
+
+#: The selection policy for every :data:`DeckProfile`, in one table.
+#:
+#: Read top-to-bottom as increasing breadth: ``authoring`` takes only the
+#: read-only built-in subset; ``survey`` takes every built-in (mutating tools
+#: included) but no app cards; ``all`` takes every built-in and every app
+#: card. Reshaping a profile is a single-row edit here — no new branch in the
+#: assembler.
+#:
+#: PORTED VERBATIM from TS ``provision.ts`` — including the
+#: authoring→``survey`` / survey→``all`` name inversion (see the module
+#: docstring's warning).
+_PROFILE_TABLE: Mapping[str, _ProfilePolicy] = MappingProxyType(
+    {
+        "authoring": _ProfilePolicy(builtins="survey", app_cards=False),
+        "survey": _ProfilePolicy(builtins="all", app_cards=False),
+        "all": _ProfilePolicy(builtins="all", app_cards=True),
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Selection
+# ---------------------------------------------------------------------------
+
+
+def cards_for_deck_profile(profile: DeckProfile) -> list[CapabilityCard]:
+    """The catalog rows a profile selects, in catalog order: the built-in
+    subset the policy names, followed by the app-novel cards when the policy
+    grants them.
+
+    Derived purely from the profile table + the catalog — no per-profile
+    branching beyond the table lookup.
+
+    :param profile: the requested deck profile
+    :raises DeckFault: ``unknown_capability`` when the profile is not in the
+        table
+    """
+    policy = _PROFILE_TABLE.get(profile)
+    if policy is None:
+        raise deck_fault(
+            "unknown_capability",
+            f'No deck profile is registered under "{profile}".',
+        )
+    builtins = cards_for_profile(policy.builtins)
+    return [*builtins, *APP_NOVEL_CARDS] if policy.app_cards else builtins
+
+
+# ---------------------------------------------------------------------------
+# Assembly
+# ---------------------------------------------------------------------------
+
+
+def _build_selected(
+    cards: Sequence[CapabilityCard], ctx: DeckContext
+) -> list[AnyCapability]:
+    """Build every selected card against a context, surfacing a typed
+    :class:`DeckFault` (``build_failed``) if any card's ``build`` throws — so
+    a single bad factory names itself instead of sinking the whole assembly
+    opaquely."""
+    built: list[AnyCapability] = []
+    for card in cards:
+        try:
+            built.append(card.build(ctx))
+        except Exception as cause:
+            raise deck_fault(
+                "build_failed",
+                f'Capability "{card.id}" failed to build.',
+                cause,
+            ) from cause
+    return built
+
+
+class _ProvisionedDeck:
+    """The assembled deck: capabilities built once at provision time, handed
+    out as fresh copies so a caller cannot mutate the backing list."""
+
+    __slots__ = ("_capabilities",)
+
+    def __init__(self, capabilities: list[AnyCapability]) -> None:
+        self._capabilities = capabilities
+
+    def tools(self) -> list[AnyCapability]:
+        return list(self._capabilities)
+
+    def box(self) -> DeckBox:
+        return list(self._capabilities)
+
+
+def provision_deck(profile: DeckProfile, ctx: DeckContext) -> _ProvisionedDeck:
+    """Provision a :class:`ToolDeck` for a profile and working context.
+
+    Looks the profile up in the profile table, selects its catalog rows,
+    builds each against ``ctx``, and returns a deck that hands the resulting
+    capabilities out two ways:
+
+    - :meth:`ToolDeck.tools` — the flat ``list[AnyCapability]`` for
+      inspection, naming, and ``--tools`` style selection.
+    - :meth:`ToolDeck.box`   — the same list (= the framework ``AgentTool``
+      list) the conductor consumes verbatim as
+      ``SessionConductorOptions.tools``.
+
+    The capabilities are built once, at provision time, and the same list
+    backs both reads (returned as fresh copies so a caller cannot mutate the
+    deck's backing list). Bridge/MCP tools are concatenated onto ``tools()``
+    by the host after provisioning; they are not part of the static selection.
+
+    :param profile: the requested capability set
+        (``authoring`` | ``survey`` | ``all``)
+    :param ctx: the working context (cwd + injectable backends) to bind cards
+        to
+    """
+    selected = cards_for_deck_profile(profile)
+    return _ProvisionedDeck(_build_selected(selected, ctx))

induscode/channels/__init__.py

@@ -0,0 +1,146 @@
+"""Channels subsystem — public barrel (port of TS ``src/channels/index.ts``).
+
+Re-exports the FROZEN channels contract: the JSON-RPC 2.0 envelope constants
+(:data:`PROTOCOL_VERSION`, :data:`OP_ERROR`, :func:`is_reply_ok`), the
+declarative operation registry (:class:`Op`, :data:`OpRegistry`,
+:func:`define_ops`), the NDJSON framer surface (:class:`NdjsonFramer` /
+:func:`encode_line` / :func:`decode_lines`), the dialog primitives
+(:class:`Ask` / :class:`Tell` / :class:`DialogBridge`), the
+:class:`ChannelContext`, the wire session projection (:data:`LinkSnapshot` /
+:func:`project_snapshot`), and the oneshot channel shapes
+(:class:`OneshotRequest` / :class:`OneshotStrategy` / :func:`run_oneshot`) —
+plus the link server, generated driver, and dialog bridge from
+:mod:`induscode.channels.link`. Consumers import the channel surface from
+``induscode.channels`` rather than reaching into individual modules.
+"""
+
+from __future__ import annotations
+
+from induscode.channels.contract import (
+    DEFAULT_CHANNEL_TIMINGS,
+    LINK_SNAPSHOT_FIELDS,
+    OP_ERROR,
+    PROTOCOL_VERSION,
+    REQUEST_ID_PREFIX,
+    Ask,
+    AskAnswer,
+    ChannelContext,
+    ChannelTimings,
+    ConductorState,
+    DialogBridge,
+    LinkSnapshot,
+    NdjsonFramer,
+    OneshotRequest,
+    OneshotShape,
+    OneshotStrategy,
+    Op,
+    OpError,
+    OpRegistry,
+    ReadableChunks,
+    RequestId,
+    SessionConductor,
+    Signal,
+    Tell,
+    ThinkingLevel,
+    Usage,
+    WritableLine,
+    define_ops,
+    is_reply_ok,
+    mint_wire_id,
+    resolve_timings,
+    signal_to_wire,
+)
+from induscode.channels.framer import decode_lines, encode_line, ndjson_framer
+from induscode.channels.link import (
+    DIALOG_TABLE,
+    DialogBridgeDeps,
+    DialogSpec,
+    LinkClient,
+    LinkDriverHandle,
+    LinkDriverIo,
+    LinkRequestError,
+    LinkServer,
+    LinkServerIo,
+    LinkedDialogBridge,
+    create_dialog_bridge,
+    create_link_driver,
+    create_link_server,
+    make_dialog_methods,
+)
+from induscode.channels.oneshot import inert_dialog, run_oneshot
+from induscode.channels.ops import (
+    OpRegistryHandle,
+    UnknownOpError,
+    build_ops,
+    dispatch,
+    has_op,
+    methods_of,
+)
+from induscode.channels.session_ops import (
+    DEFAULT_THINKING,
+    SESSION_OPS,
+    project_snapshot,
+)
+
+__all__ = [
+    "Ask",
+    "AskAnswer",
+    "ChannelContext",
+    "ChannelTimings",
+    "ConductorState",
+    "DEFAULT_CHANNEL_TIMINGS",
+    "DEFAULT_THINKING",
+    "DIALOG_TABLE",
+    "DialogBridge",
+    "DialogBridgeDeps",
+    "DialogSpec",
+    "LINK_SNAPSHOT_FIELDS",
+    "LinkClient",
+    "LinkDriverHandle",
+    "LinkDriverIo",
+    "LinkRequestError",
+    "LinkServer",
+    "LinkServerIo",
+    "LinkSnapshot",
+    "LinkedDialogBridge",
+    "NdjsonFramer",
+    "OP_ERROR",
+    "OneshotRequest",
+    "OneshotShape",
+    "OneshotStrategy",
+    "Op",
+    "OpError",
+    "OpRegistry",
+    "OpRegistryHandle",
+    "PROTOCOL_VERSION",
+    "REQUEST_ID_PREFIX",
+    "ReadableChunks",
+    "RequestId",
+    "SESSION_OPS",
+    "SessionConductor",
+    "Signal",
+    "Tell",
+    "ThinkingLevel",
+    "UnknownOpError",
+    "Usage",
+    "WritableLine",
+    "build_ops",
+    "create_dialog_bridge",
+    "create_link_driver",
+    "create_link_server",
+    "decode_lines",
+    "define_ops",
+    "dispatch",
+    "encode_line",
+    "has_op",
+    "inert_dialog",
+    "is_reply_ok",
+    "make_dialog_methods",
+    "methods_of",
+    "mint_wire_id",
+    "ndjson_framer",
+    "project_snapshot",
+    "resolve_timings",
+    "run_oneshot",
+    "signal_to_wire",
+]