cave-teams 0.1.0__tar.gz

cave_teams-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sancovp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cave_teams-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: cave-teams
+Version: 0.1.0
+Summary: Connect AI agents like code — compose any agents into teams with a tiny algebra, all topologies, a programmable message state machine, and a proven-team library. CAVE = Coding Agent Virtualization Environment.
+Author: sancovp
+License: MIT
+Project-URL: Homepage, https://github.com/sancovp/cave-teams
+Project-URL: Repository, https://github.com/sancovp/cave-teams
+Keywords: ai-agents,agents,multi-agent,multi-agent-systems,agent-orchestration,agent-framework,ai-agent-framework,llm,llm-agents,llm-orchestration,agentic,agentic-ai,agentic-workflow,claude,claude-code,codex,minimax,orchestration,agent-teams,provider-agnostic,dsl,cave
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: minimax
+Requires-Dist: anthropic>=0.40; extra == "minimax"
+Dynamic: license-file
+
+# cave-teams
+
+**Connect AI agents like code.** Wire your whole team of AI agents with one line instead of hundreds
+of lines of glue — add one, swap one, or reuse a whole team just by changing a word.
+
+cave-teams is the **programmable, provider-agnostic** version of Claude Code Teams. The agents
+underneath can be anything (Claude Code, Codex, MiniMax, a model call, a shell command, a Python
+function); you control the *flow* with code. **CAVE = Coding Agent Virtualization Environment.**
+
+```bash
+pip install cave-teams        # zero-dependency core
+```
+
+## The one idea
+
+Everything is the same shape — a building block. An agent is one, a team is one, a whole world is
+one. A composition of building blocks *is* a building block, so teams nest inside teams forever
+(`agent = team = world`). That is why two operators wire anything:
+
+```python
+import cave_teams
+from cave_teams import AgentLink
+
+research = AgentLink("research", "Find 3 key facts.")
+writer   = AgentLink("writer",   "Turn the facts into a paragraph.")
+
+team = research >> writer                      # >>  run in order
+flow = research >> (security | perf | tests) >> ship   # |  run at the same time
+
+result = await flow.execute({"goal": "ship the feature"})
+```
+
+## What it does
+
+- **Program any control flow** — agents fire on conditions you write (`when_flag`, `after`, any
+  predicate). The message state machine, not a markdown to-do list.
+- **Any agents** — `AgentLink` (Claude Code / MiniMax), `HeavenMiniMaxLink` (a real coding agent
+  with bash + file-edit), or `lift()` any function / callable.
+- **Every topology** — sequential, parallel, branch, loop-until-approved, join (DAG), typed
+  hand-off, shared-workspace arena, tournament, evolve, season — and they nest.
+- **Provable wiring** — termination, gate-soundness, and distribution are mechanically tested.
+- **A whole world of agents** — `GameWorld`, an economic crafter sim, agents that compete and evolve.
+- **Build once, reuse forever** — save a proven team to your golden library and drop it into any
+  project as one building block.
+
+## Two layers
+
+- **The native API** is how you program — the `>>` / `|` DSL and the pattern functions.
+- **`cave()`** is the metacontrol function on top: it drives the whole API from a data spec, in any
+  sequence — serialize a team, run it from JSON, save/reuse a proven team, federate caves.
+
+## Claude Code plugin
+
+This repo is also a Claude Code plugin (`plugin/`). It ships a skill per pattern — the language
+(`cave-teams`), the metacontrol (`cave`), and one each for sequential / parallel / branch / gate /
+conditions / dovetail / dag / blackboard / tournament / evolve / season / world / sim / metacog.
+`.claude/skills`, `.codex/skills`, and `.agent/skills` symlink to the same `plugin/skills`, so any
+coding agent that clones the repo picks them up.
+
+MIT.

cave_teams-0.1.0/README.md

@@ -0,0 +1,60 @@
+# cave-teams
+
+**Connect AI agents like code.** Wire your whole team of AI agents with one line instead of hundreds
+of lines of glue — add one, swap one, or reuse a whole team just by changing a word.
+
+cave-teams is the **programmable, provider-agnostic** version of Claude Code Teams. The agents
+underneath can be anything (Claude Code, Codex, MiniMax, a model call, a shell command, a Python
+function); you control the *flow* with code. **CAVE = Coding Agent Virtualization Environment.**
+
+```bash
+pip install cave-teams        # zero-dependency core
+```
+
+## The one idea
+
+Everything is the same shape — a building block. An agent is one, a team is one, a whole world is
+one. A composition of building blocks *is* a building block, so teams nest inside teams forever
+(`agent = team = world`). That is why two operators wire anything:
+
+```python
+import cave_teams
+from cave_teams import AgentLink
+
+research = AgentLink("research", "Find 3 key facts.")
+writer   = AgentLink("writer",   "Turn the facts into a paragraph.")
+
+team = research >> writer                      # >>  run in order
+flow = research >> (security | perf | tests) >> ship   # |  run at the same time
+
+result = await flow.execute({"goal": "ship the feature"})
+```
+
+## What it does
+
+- **Program any control flow** — agents fire on conditions you write (`when_flag`, `after`, any
+  predicate). The message state machine, not a markdown to-do list.
+- **Any agents** — `AgentLink` (Claude Code / MiniMax), `HeavenMiniMaxLink` (a real coding agent
+  with bash + file-edit), or `lift()` any function / callable.
+- **Every topology** — sequential, parallel, branch, loop-until-approved, join (DAG), typed
+  hand-off, shared-workspace arena, tournament, evolve, season — and they nest.
+- **Provable wiring** — termination, gate-soundness, and distribution are mechanically tested.
+- **A whole world of agents** — `GameWorld`, an economic crafter sim, agents that compete and evolve.
+- **Build once, reuse forever** — save a proven team to your golden library and drop it into any
+  project as one building block.
+
+## Two layers
+
+- **The native API** is how you program — the `>>` / `|` DSL and the pattern functions.
+- **`cave()`** is the metacontrol function on top: it drives the whole API from a data spec, in any
+  sequence — serialize a team, run it from JSON, save/reuse a proven team, federate caves.
+
+## Claude Code plugin
+
+This repo is also a Claude Code plugin (`plugin/`). It ships a skill per pattern — the language
+(`cave-teams`), the metacontrol (`cave`), and one each for sequential / parallel / branch / gate /
+conditions / dovetail / dag / blackboard / tournament / evolve / season / world / sim / metacog.
+`.claude/skills`, `.codex/skills`, and `.agent/skills` symlink to the same `plugin/skills`, so any
+coding agent that clones the repo picks them up.
+
+MIT.

cave_teams-0.1.0/cave_teams/__init__.py

@@ -0,0 +1,99 @@
+"""
+CAVE Teams — Programmable agent teams with persistent conversations.
+
+Core:
+    Conversation      — Persistent agent conversation (remembers everything)
+    Harness           — File watcher that delivers messages between agents
+    TeamLeader        — Opus/MiniMax leader that orchestrates by reasoning
+
+Primitives:
+    run_opus()        — Single claude -p call with Opus 4.6 1M
+    continue_opus()   — Continue a prior claude -p conversation
+    run_minimax()     — Direct MiniMax call
+
+Seam + frontend + adaptor (the 2026-06 build — events OUT, decoupled frontend):
+    EventBus, TeamEvent   — the on_event seam every Harness now emits through
+    TeamGalleryServer     — the live web gallery (/ws + /emit + page)
+    FrontendListener / HttpFrontendListener — push a team's events to the gallery
+    build_team / spawn_team — the CAVE adaptor: spin up a team on the fly, wired live
+
+Legacy (stateless, being replaced):
+    Team, TeamAgent   — Old stateless orchestrator
+"""
+
+from .primitives import run_opus, continue_opus, run_minimax, generate_image, AgentResult, ImageResult
+from .conversation import Conversation
+from .events import EventBus, TeamEvent, FileListener, CallbackListener
+from .harness import Harness, Condition
+from .conditions import (
+    when_flag, when_not_flag, after, when, all_of, any_of, wrap_cave_automation,
+)
+# the REAL chain ontology (vendored from SDNA — pure stdlib) + the typed Dovetail data-plane +
+# cave-teams' ConcurrentChain. cave-teams is chain-ontology NATIVE: every agent type is a Link.
+from .chain_ontology import (
+    Link, LinkResult, LinkStatus, Chain, EvalChain, Compiler, ConfigLink, LinkConfig,
+)
+from .concurrent import ConcurrentChain
+from .dovetail import DovetailModel, HermesConfigInput
+from .links import AgentLink
+# A MiniMax agent via the heaven framework (the onionmorph/Conductor path — self-auths, no env key).
+# heaven_base/cave are imported lazily inside execute(), so this import is host-safe (zero heaven dep).
+from .heaven_minimax import HeavenMiniMaxLink, build_minimax_config, minimax_coords
+# The metacontrol function: ONE super-compiled top that can drive the whole native API from a
+# data spec, in any sequence. NOT how you program (use the native API for that) — the universal
+# driver over it, extensible via register() (canonical/goldenized ops). See cave.py.
+from .cave import (
+    cave, golden, register, register_fn, registered_ops, registered_fns,
+    scan_caves, scan_library, _build as build_from_spec,
+)
+from . import topologies
+from .topologies import (
+    pipeline, chain, fan_out, broadcast, synthesis_gate, map_reduce, tournament,
+    eval_chain, loop_refine, duo, round_robin, Router, router, chain_from_spec,
+)
+# a team AS an agent (homoiconic: agent = team = agent = Link) → runtime stacking + override-run
+from .runtime import TeamRuntime, as_agent
+# Phase 2: the SDNA/heaven agent zoo as leaf Links (as_link adapts any runnable; SDNAC is already a Link)
+from .sdna_bridge import as_link, RunnableLink, SDNA_AVAILABLE
+from .chain_ontology import CHAIN_ONTOLOGY_SOURCE
+# Phase 3: the agent-composition ALGEBRA over Links (laws in LAWS.md, verified in test_algebra_laws.py)
+from . import algebra
+from .algebra import seq, par, choice, gate, dovetail, skip, team, lift, Skip, Subgraph
+# Phase 4: literal algebra NOTATION (a >> b, a | b, >> dove(D) >>) — installs >>/| on Link
+from . import dsl
+from .dsl import dove
+# Team topology: the general partial-order scheduler (blockedBy DAG) — seq/par are its limits
+from .dag import dag, DagChain
+# Team topology: the arena / stigmergy blackboard (the gameworld core) — N agents ↔ shared state ↔ deity
+from .blackboard import blackboard, Blackboard
+# The genetic operator: copy a winner's dir (its AIOS) + wipe session memory → next generation
+from .evolve import evolve, evolve_dir, select_winners
+# The Economic Crafter Sim: compete → user-buys → select → evolve over generations (compiler + lab)
+from .sim import crafter_sim
+# The bounded epoch: carry / reset / ratchet boundary (the WoS season — the standard climbs)
+from .season import season, Season, carry_reset_ratchet
+# A WHOLE gameworld as one composable object: a program, and a class (instantiable / from_spec / subclassable)
+from .gameworld import GameWorld, world_as_agent
+# Workflow-tool parity: pipeline (no-barrier streaming), parallel (capped), run_until, content-hash
+# resume (Memo), schema-output (with_schema). `pipeline` stays module-qualified (cave_teams.workflow.pipeline)
+# to avoid clashing with topologies.pipeline (the sequential Chain builder).
+from . import workflow
+from .workflow import parallel, run_until, Memo, content_key, with_schema, SchemaError
+# NPCs: agents in the world callable by players via a skill (an NPC can be a whole GameWorld)
+from .npc import npc_mutator
+# Context surgery (inject / weave / dovetail) — the context-assembly plane (native + sdna re-export)
+from . import context_engineering
+from .context_engineering import compose_context, weave_text, inject_context, weave_context, CONTEXT_ENGINEERING_SOURCE
+# Metacog shell (a SEPARATE meta-pattern): executor→observer→meta[STATIC]→skill_editor, compounds
+from .metacog import metacog_shell, MetacogShell
+from .leader import TeamLeader
+from .orchestrator import Team, TeamAgent, AgentBackend, Task
+from .jobworld import JobworldTeam
+from .adaptor import build_team, spawn_team
+
+# Frontend imports fastapi/uvicorn lazily — keep them optional so the core library
+# (agents + seam + adaptor) imports cleanly even where the web deps aren't installed.
+try:
+    from .frontend import TeamGalleryServer, FrontendListener, HttpFrontendListener
+except Exception:  # pragma: no cover
+    pass

cave_teams-0.1.0/cave_teams/_chain_ontology_vendored.py

@@ -0,0 +1,395 @@
+# VENDORED VERBATIM from base/sdna/sdna/chain_ontology.py (pure stdlib — abc/dataclasses/enum/typing,
+# zero heaven/LLM coupling). Copied (not reimplemented) into cave-teams so the library is chain-ontology
+# NATIVE while staying standalone (no `import sdna`, which would trigger heaven-coupled sdna/__init__).
+# This is THE ontology — keep it in sync if SDNA's changes. cave-teams adds ConcurrentChain in concurrent.py.
+"""Universal Chain Ontology — Link and Chain homoiconic primitives.
+
+The entire SDNA hierarchy reduces to two concepts:
+
+    Link: atomic unit of execution (wraps a config)
+    Chain(Link): sequence of Links — which IS ALSO a Link
+
+This gives homoiconic composition: a Chain can be a Link in another Chain,
+so SDNAC, SDNAFlow, SDNAFlowchain, DUOChain all become specializations of
+the same two primitives.
+
+    SDNAC            = Link (ariadne + hermes config)
+    SDNAFlow         = Chain (sequential links)
+    SDNAFlowchain    = EvalChain (chain + OVP link in a loop)
+    DUOChain         = DUOChain (A→P alternation chain)
+    CompiledAgent    = Link | Chain (pipeline output)
+
+Source: Heaven core/chains/base/link.py + base_chain.py
+Extracted from llegos actor model — we keep only the composition,
+not the message-passing substrate.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+
+# =============================================================================
+# Result protocol
+# =============================================================================
+
+class LinkStatus(str, Enum):
+    SUCCESS = "success"
+    BLOCKED = "blocked"
+    ERROR = "error"
+    AWAITING_INPUT = "awaiting_input"
+
+
+@dataclass
+class LinkResult:
+    """Result of executing a Link."""
+    status: LinkStatus
+    context: Dict[str, Any] = field(default_factory=dict)
+    error: Optional[str] = None
+    resume_path: Optional[List[int]] = None
+
+
+# =============================================================================
+# Link — atomic unit
+# =============================================================================
+
+class Link(ABC):
+    """Atomic unit of execution in the universal chain ontology.
+
+    A Link wraps a configuration and knows how to execute itself.
+    Everything in SDNA is a Link — single units, flows, flowchains.
+
+    The homoiconic property: Chain extends Link, so a Chain
+    can appear as a Link inside another Chain. This is the
+    entire composition model.
+
+    Contract:
+        - name: str (attribute or property — both work)
+        - execute(context) → LinkResult (or compatible result type)
+
+    SDNA compatibility: SDNAC sets self.name in __init__ (attribute),
+    which satisfies this contract. Subclasses may also use @property.
+    """
+
+    # name can be set as attribute in __init__ or as @property
+    # We don't make it @abstractmethod to allow plain attributes
+    name: str
+
+    @abstractmethod
+    async def execute(self, context: Optional[Dict[str, Any]] = None, **kwargs):
+        """Execute this link with the given context.
+
+        Args:
+            context: Shared mutable context dictionary.
+            **kwargs: Subclass-specific params (e.g. on_message for SDNAC).
+
+        Returns:
+            Result with status and updated context.
+            Type varies by subclass (SDNAResult, SDNAFlowchainResult, etc.)
+        """
+        ...
+
+    def describe(self, depth: int = 0) -> str:
+        """Return an LLM-readable description of this link.
+
+        This is the metaprogramming surface. LLMs call this to inspect
+        the chain structure they just built. Without this, homoiconic
+        composition has no consumer.
+
+        EVENTUAL BEHAVIOR (not yet implemented):
+            1. Send this object's AST to ontologization (Carton/YOUKNOW)
+               if not already represented in the ontology
+            2. Query the ontology for what it knows about this Link
+            3. Return the ontology CLI info — effectively starting a
+               non-interactive persistent session about this object
+
+        Goes as deep as the callgraph but doesn't show everything
+        all at once — progressive pagination. The LLM can drill
+        deeper by following references, not by receiving a wall.
+
+        So: str(link) becomes a live ontology query, not a static string.
+        The object describes itself through the knowledge graph.
+
+        Current: static format string, overridden per subclass.
+        Future: ontology-backed self-description with pagination.
+        """
+        indent = "  " * depth
+        return f"{indent}Link \"{self.name}\""
+
+    def __str__(self) -> str:
+        """String representation = ontology CLI session about this object.
+
+        Eventually: calling str() on any Link starts an ontology CLI
+        non-interactive persistent session about that thing. The AST
+        gets sent to ontologization if not in ontology, the ontology
+        gets queried, and the CLI info comes back.
+
+        Progressive pagination: shows the top level, with references
+        the LLM can follow to go deeper. Never dumps the full tree.
+
+        For now: delegates to describe().
+        """
+        return self.describe()
+
+
+# =============================================================================
+# Chain(Link) — homoiconic sequence
+# =============================================================================
+
+class Chain(Link):
+    """Sequence of Links — which IS ALSO a Link.
+
+    This is the homoiconic composition primitive.
+    A Chain can be a Link in another Chain, giving recursive nesting:
+
+        Chain([Link, Chain([Link, Link]), Link])
+
+    Execution is sequential: each link gets the context from the previous.
+    Stops on first non-SUCCESS.
+    """
+
+    def __init__(self, chain_name: str, links: Optional[List[Link]] = None):
+        self._name = chain_name
+        self.links: List[Link] = links or []
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def add(self, link: Link) -> "Chain":
+        """Add a link to the chain. Returns self for fluent API."""
+        self.links.append(link)
+        return self
+
+    async def execute(self, context: Optional[Dict[str, Any]] = None, **kwargs):
+        """Execute links sequentially. Stop on first failure."""
+        ctx = dict(context) if context else {}
+
+        for i, link in enumerate(self.links):
+            result = await link.execute(ctx)
+            ctx = result.context
+
+            if result.status != LinkStatus.SUCCESS:
+                result.resume_path = [i] + (result.resume_path or [])
+                return result
+
+        return LinkResult(status=LinkStatus.SUCCESS, context=ctx)
+
+    def __len__(self) -> int:
+        return len(self.links)
+
+    def __getitem__(self, index: int) -> Link:
+        return self.links[index]
+
+    def describe(self, depth: int = 0) -> str:
+        """Recursive tree description of the chain."""
+        indent = "  " * depth
+        lines = [f"{indent}Chain \"{self.name}\" ({len(self.links)} links):"]
+        for i, link in enumerate(self.links):
+            connector = "└──" if i == len(self.links) - 1 else "├──"
+            child_desc = link.describe(depth + 1).lstrip()
+            lines.append(f"{indent}  {connector} {child_desc}")
+        return "\n".join(lines)
+
+
+# =============================================================================
+# EvalChain(Chain) — chain + evaluator in a loop
+# =============================================================================
+
+class EvalChain(Chain):
+    """Chain with an evaluator Link in a loop.
+
+    Runs the inner chain, then runs the evaluator.
+    If evaluator approves → done. Otherwise loop (max_cycles).
+
+    This is SDNAFlowchain / OVP pattern.
+    """
+
+    def __init__(
+        self,
+        chain_name: str,
+        links: Optional[List[Link]] = None,
+        evaluator: Optional[Link] = None,
+        max_cycles: int = 3,
+        approval_key: str = "approved",
+    ):
+        super().__init__(chain_name, links)
+        self.evaluator = evaluator
+        self.max_cycles = max_cycles
+        self.approval_key = approval_key
+
+    async def execute(self, context: Optional[Dict[str, Any]] = None, **kwargs):
+        """Run chain → evaluate → loop."""
+        ctx = dict(context) if context else {}
+
+        for cycle in range(self.max_cycles):
+            ctx["cycle"] = cycle + 1
+
+            # Run inner chain
+            result = await super().execute(ctx)
+            ctx = result.context
+
+            if result.status != LinkStatus.SUCCESS:
+                return result
+
+            # If no evaluator, single pass
+            if not self.evaluator:
+                return result
+
+            # Evaluate
+            eval_result = await self.evaluator.execute(ctx)
+            ctx = eval_result.context
+
+            if eval_result.status != LinkStatus.SUCCESS:
+                return eval_result
+
+            if ctx.get(self.approval_key):
+                return LinkResult(status=LinkStatus.SUCCESS, context=ctx)
+
+        return LinkResult(
+            status=LinkStatus.BLOCKED,
+            context=ctx,
+            error=f"Max cycles ({self.max_cycles}) reached",
+        )
+
+    def describe(self, depth: int = 0) -> str:
+        indent = "  " * depth
+        lines = [f"{indent}EvalChain \"{self.name}\" ({len(self.links)} links, max_cycles={self.max_cycles}):"]
+        for i, link in enumerate(self.links):
+            connector = "├──" if i < len(self.links) - 1 or self.evaluator else "└──"
+            child_desc = link.describe(depth + 1).lstrip()
+            lines.append(f"{indent}  {connector} {child_desc}")
+        if self.evaluator:
+            eval_desc = self.evaluator.describe(depth + 1).lstrip()
+            lines.append(f"{indent}  └── [evaluator] {eval_desc}")
+        return "\n".join(lines)
+
+
+# =============================================================================
+# Compiler(Chain) — chain that produces new Links/Chains
+# =============================================================================
+
+class Compiler(Chain):
+    """A Chain whose output is a Link or Chain.
+
+    This is the D:D→D type in the hierarchy:
+
+        Link           — executes
+        Chain(Link)    — executes Links in sequence
+        Compiler(Chain) — executes Links that PRODUCE new Links
+
+    A Compiler takes a specification (as context) and produces
+    executable structure (a Link/Chain) as output. The produced
+    structure is stored in context under the 'compiled' key.
+
+    This is what makes the system self-compiling: a Compiler
+    can compile another Compiler, and the output is always
+    something that can be composed and executed.
+    """
+
+    def __init__(
+        self,
+        chain_name: str,
+        links: Optional[List[Link]] = None,
+        output_key: str = "compiled",
+    ):
+        super().__init__(chain_name, links)
+        self.output_key = output_key
+
+    def get_compiled(self, context: Dict[str, Any]) -> Optional[Link]:
+        """Extract the compiled Link/Chain from context."""
+        return context.get(self.output_key)
+
+    def describe(self, depth: int = 0) -> str:
+        indent = "  " * depth
+        lines = [f"{indent}Compiler \"{self.name}\" ({len(self.links)} links):"]
+        for i, link in enumerate(self.links):
+            connector = "└──" if i == len(self.links) - 1 else "├──"
+            child_desc = link.describe(depth + 1).lstrip()
+            lines.append(f"{indent}  {connector} {child_desc}")
+        lines.append(f"{indent}  → produces Link via '{self.output_key}'")
+        return "\n".join(lines)
+
+
+# =============================================================================
+# ConfigLink — concrete Link wrapping a config dict
+# =============================================================================
+
+@dataclass
+class LinkConfig:
+    """Configuration for a Link — the serializable part.
+
+    This is what the compiler produces. At runtime, a LinkConfig
+    becomes a Link via a factory/bridge.
+
+    Maps to HermesConfig fields:
+    - name            → identity
+    - goal            → input prompt (what to do)
+    - system_prompt   → behavioral frame
+    - model           → which LLM
+    - provider        → which API
+    - temperature     → creativity
+    - max_turns       → execution limit
+    - permission_mode → trust boundary
+    - allowed_tools   → tool surface
+    - mcp_servers     → MCP configs
+    - skills          → injected skill context
+    """
+    name: str = ""
+    goal: str = ""
+    system_prompt: str = ""
+    model: str = ""
+    provider: str = ""
+    temperature: float = 0.7
+    max_turns: int = 10
+    permission_mode: str = "default"
+    allowed_tools: List[str] = field(default_factory=list)
+    mcp_servers: Dict[str, Any] = field(default_factory=dict)
+    skills: str = ""  # injected context
+    passthrough: Dict[str, Any] = field(default_factory=dict)
+
+
+class ConfigLink(Link):
+    """Concrete Link that wraps a LinkConfig.
+
+    This is the leaf node — the thing that actually holds the config
+    the compiler produced. At runtime, this gets converted to an
+    SDNAC with the appropriate AriadneChain and HermesConfig.
+    """
+
+    def __init__(self, config: LinkConfig):
+        self.config = config
+
+    @property
+    def name(self) -> str:
+        return self.config.name
+
+    async def execute(self, context: Optional[Dict[str, Any]] = None, **kwargs):
+        """Placeholder execute — real execution creates an SDNAC and runs it.
+
+        In test/dry-run mode, this just passes through.
+        In production, the config gets instantiated as an SDNAC.
+        """
+        ctx = dict(context) if context else {}
+        ctx["_link_config"] = self.config
+        ctx["_link_name"] = self.config.name
+        return LinkResult(status=LinkStatus.SUCCESS, context=ctx)
+
+    def describe(self, depth: int = 0) -> str:
+        indent = "  " * depth
+        parts = [f'Link "{self.config.name}"']
+        if self.config.model:
+            parts.append(f"model={self.config.model}")
+        if self.config.temperature != 0.7:
+            parts.append(f"temp={self.config.temperature}")
+        if self.config.goal:
+            goal_preview = self.config.goal[:60]
+            if len(self.config.goal) > 60:
+                goal_preview += "..."
+            parts.append(f'goal="{goal_preview}"')
+        if self.config.allowed_tools:
+            parts.append(f"tools=[{', '.join(self.config.allowed_tools[:5])}]")
+        return f"{indent}{' | '.join(parts)}"