agentic-dev-loop 0.9.2__py3-none-any.whl → 0.10.2__py3-none-any.whl

agentic_dev_loop/core/config.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import hashlib
+import importlib.metadata
 import re
 import warnings
 from pathlib import Path
@@ -396,9 +397,13 @@ class StepConfig(BaseModel):
     terminal_timeout: float | None = Field(default=None, gt=0)  # seconds, agent steps only (032)
     finalize_nudge_turns: int | None = Field(default=None, gt=0)  # agent steps only (035)
     brief_inputs: BriefInputsSpec | None = None  # agent steps only (033)
-    # 047 (D7): per-step opt-in override; unset falls back to the llm block,
-    # then the SDK default. Full SDK literal, passthrough semantics.
+    # 047 (D7) / 054 (D6): per-step opt-in override; unset falls back to the
+    # effective profile's value (the named `llms:` profile, else the `llm:`
+    # block), else reasoning is off. Full SDK literal, passthrough semantics.
     reasoning_effort: ReasoningEffort | None = None
+    # 054 (D3): names a top-level `llms:` profile; the whole profile moves
+    # together (model, endpoint, key, effort default). None = the `llm:` block.
+    llm: str | None = None
     custom_prompt: str | None = None  # agent steps only (040); file path resolved at load
     env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
     setup: str | None = None  # command or agent steps; runs fresh at each step entry (052)
@@ -486,6 +491,16 @@ class StepConfig(BaseModel):
                 f"step {self.name!r}: exactly one of 'agent', 'action', "
                 "'command', or 'brief_inputs' is required"
             )
+        if self.llm is not None:
+            if not self.llm.strip():
+                raise ValueError(
+                    f"step {self.name!r}: 'llm' must be a non-empty profile name"
+                )
+            if self.kind not in ("agent", "brief"):
+                raise ValueError(
+                    f"step {self.name!r}: 'llm' names an LLM profile and is "
+                    "only allowed on 'agent' or 'brief_inputs' steps"
+                )
         if self.brief_inputs is not None:
             if self.produces:
                 raise ValueError(
@@ -587,9 +602,9 @@ class LlmConfig(BaseModel):
     base_url: str | None = None
     api_key_env: str
     timeout: float | None = None  # omitted → opinionated no-timeout default
-    # 047 (D1): opt-in passthrough; unset means the field is not passed at
-    # all, so the SDK default ("high") applies and today's behavior is
-    # byte-identical. No default may move without an observed run (D6).
+    # 047 (D1) / 054 (D6): opt-in passthrough; unset means reasoning is off
+    # (the engine forwards none and strips reasoning passback). The SDK
+    # "high" default never engages because build_llm always passes the value.
     reasoning_effort: ReasoningEffort | None = None
 
 
@@ -606,6 +621,9 @@ class PipelineConfig(BaseModel):
     extensions_dir: str = "~/.agentic-dev-loop/extensions"
     env_allowlist: list[str] = []
     llm: LlmConfig
+    # 054 (D1): named LLM profiles, each a strict LlmConfig. Optional and
+    # purely additive - the `llm:` block above remains the default.
+    llms: dict[str, LlmConfig] = {}
     isolation: IsolationConfig | None = None  # None = always-on defaults
     state_dir: str = ".pr"  # default relocated to ~/.agentic-dev-loop/runs/<hash>/ at load
     secrets: dict[str, SecretSpec] = {}  # ref name -> locator; values never appear here
@@ -630,6 +648,9 @@ class PipelineConfig(BaseModel):
     # edit instead of raising. Same declared-path vocabulary as
     # ``sync_excludes:``.
     merge_on_conflict: list[str] = []
+    # 055: the toolchain profile resolved at load time. Kept on the validated
+    # config so the run records which profile supplied its defaults.
+    profile: str | None = None
 
     @field_validator("deps_policy")
     @classmethod
@@ -690,6 +711,23 @@ class PipelineConfig(BaseModel):
                 "enforces, or set 'deps_policy: open'")
         return self
 
+    @model_validator(mode="after")
+    def _check_llm_profiles(self) -> "PipelineConfig":
+        """054 (D5): the registry is additive and referential. A profile
+        literally named 'default' is rejected (the `llm:` block already is the
+        default), and any step naming an undeclared profile fails at load,
+        never mid-run."""
+        if "default" in self.llms:
+            raise ValueError(
+                "'llms' cannot declare a profile named 'default' - the "
+                "top-level 'llm:' block is already the default")
+        for step in self.steps:
+            if step.llm is not None and step.llm not in self.llms:
+                raise ValueError(
+                    f"step {step.name!r}: unknown LLM profile {step.llm!r} - "
+                    f"declared profiles: {sorted(self.llms)}")
+        return self
+
     @model_validator(mode="after")
     def _mounts_avoid_state_dir(self) -> "PipelineConfig":
         """BR-1.3: the host-only run-state dir is never a mount path.
@@ -858,6 +896,21 @@ def load_config(path: Path) -> PipelineConfig:
         raise ValueError(
             f"pipeline config must be a mapping, got {type(data).__name__}: {path}"
         )
+    profile_ref = data.pop("profile", None)
+    if profile_ref is not None:
+        from agentic_dev_loop.core.profiles import (
+            ProfileError,
+            load_profile,
+            merge_profile,
+        )
+
+        try:
+            installed = importlib.metadata.version("agentic-dev-loop")
+            profile = load_profile(str(profile_ref), installed)
+            data = merge_profile(data, profile)
+        except ProfileError as exc:
+            raise ValueError(f"pipeline {path}: {exc}") from exc
+        data["profile"] = profile_ref
     if "state_dir" not in data:
         data["state_dir"] = default_state_dir(path)
     cfg = PipelineConfig.model_validate(data)

agentic_dev_loop/core/profiles/__init__.py

@@ -0,0 +1,178 @@
+"""Toolchain profiles: bundled data plus the load-time merge into a pipeline.
+
+A profile supplies the environment facts every app on a toolchain shares
+(isolation image, caches, premise files, gitignore lines, doctor probes).
+Profiles never carry commands, gates, or steps - those live in
+engine-resident recipes. The subpackage is intentionally dependency-light
+(stdlib + pydantic + PyYAML) so ``core`` can resolve a profile at config
+load time without importing the engine.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib import resources
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "PremiseFile",
+    "Profile",
+    "ProfileError",
+    "ProfileIsolation",
+    "bundled_profile_names",
+    "check_engine_min",
+    "load_profile",
+    "merge_profile",
+    "parse_version",
+]
+
+_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:(a|b|rc)(\d+))?$")
+_RANK = {"a": 0, "b": 1, "rc": 2}
+_FINAL = 3
+
+
+class ProfileError(ValueError):
+    """Any profile load, parse, or compatibility failure."""
+
+
+class PremiseFile(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    content: str
+
+
+class ProfileIsolation(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    image: str
+    seccomp_profile: str | None = None
+    cpus: int
+
+
+class Profile(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    engine_min: str
+    description: str = ""
+    isolation: ProfileIsolation
+    caches: list[str] = Field(default_factory=list)
+    premise_files: list[PremiseFile] = Field(default_factory=list)
+    gitignore_additions: list[str] = Field(default_factory=list)
+    doctor_checks: list = Field(default_factory=list)
+
+
+def parse_version(text: str) -> tuple[int, int, int, int, int]:
+    """Parse ``X.Y.Z[a|b|rcN]`` into a directly comparable 5-tuple.
+
+    Rank ordering is alpha < beta < rc < final; the prerelease number is 0
+    for a final release so ``1.0.0rc9 < 1.0.0``.
+    """
+    match = _VERSION_RE.match(text.strip())
+    if match is None:
+        raise ProfileError(f"unparseable version: {text!r}")
+    major, minor, patch, pre, num = match.groups()
+    if pre is None:
+        return (int(major), int(minor), int(patch), _FINAL, 0)
+    return (int(major), int(minor), int(patch), _RANK[pre], int(num))
+
+
+def check_engine_min(engine_min: str, installed: str,
+                     latest: str | None = None) -> None:
+    """Raise unless ``installed`` satisfies ``engine_min``.
+
+    ``latest`` is substituted into the fix line by the caller (doctor); when
+    omitted the floor itself is used.
+    """
+    if parse_version(installed) < parse_version(engine_min):
+        target = latest or engine_min
+        raise ProfileError(
+            f"profile requires engine >= {engine_min}; installed {installed}. "
+            f'Upgrade: pipx install --force "agentic-dev-loop=={target}"')
+
+
+def _data_dir():
+    return resources.files(__package__).joinpath("data")
+
+
+def bundled_profile_names() -> list[str]:
+    return sorted(
+        entry.name[: -len(".yaml")]
+        for entry in _data_dir().iterdir()
+        if entry.name.endswith(".yaml")
+    )
+
+
+def _read_yaml(text: str, source: str) -> dict:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ProfileError(f"profile {source!r}: invalid YAML: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ProfileError(f"profile {source!r} must be a mapping")
+    return data
+
+
+def _validate(data: dict, source: str) -> Profile:
+    try:
+        return Profile.model_validate(data)
+    except Exception as exc:
+        raise ProfileError(f"profile {source!r}: {exc}") from exc
+
+
+def load_profile(reference: str, installed_version: str) -> Profile:
+    """Load a bundled profile by name or a consumer profile by path.
+
+    Existence decides: a filesystem path that exists is read as a consumer
+    profile; anything else must name a bundled profile.
+    """
+    candidate = Path(reference)
+    if candidate.is_file():
+        data = _read_yaml(candidate.read_text(encoding="utf-8"), reference)
+        profile = _validate(data, reference)
+    else:
+        names = bundled_profile_names()
+        if reference not in names:
+            raise ProfileError(
+                f"unknown profile '{reference}'; bundled profiles: "
+                + ", ".join(names))
+        entry = _data_dir().joinpath(f"{reference}.yaml")
+        data = _read_yaml(entry.read_text(encoding="utf-8"), reference)
+        if data.get("name") != reference:
+            raise ProfileError(
+                f"profile {reference!r}: declared name {data.get('name')!r} "
+                f"does not match its filename")
+        profile = _validate(data, reference)
+    check_engine_min(profile.engine_min, installed_version)
+    return profile
+
+
+def _dedupe(items: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for item in items:
+        if item not in seen:
+            seen.add(item)
+            out.append(item)
+    return out
+
+
+def merge_profile(data: dict, profile: Profile) -> dict:
+    """Merge a profile into a pipeline dict; the pipeline wins.
+
+    Isolation merges key-wise (profile under, pipeline over). Caches union
+    profile-first, dedupe-preserving-order. Every other key is untouched.
+    """
+    merged = dict(data)
+    profile_iso = profile.isolation.model_dump(exclude_none=True)
+    pipeline_iso = merged.get("isolation") or {}
+    if not isinstance(pipeline_iso, dict):
+        pipeline_iso = {}
+    merged["isolation"] = {**profile_iso, **pipeline_iso}
+    caches = _dedupe(list(profile.caches) + list(merged.get("caches") or []))
+    merged["caches"] = caches
+    return merged

agentic_dev_loop/core/profiles/data/dotnet-node.yaml

@@ -0,0 +1,22 @@
+name: dotnet-node
+engine_min: 0.9.2
+description: .NET backend with a Node.js frontend
+isolation:
+  image: ghcr.io/lukedawilson/agentic-dev-loop/dev-dotnet@sha256:d15d1c6115fafc3d5f3bfb567338d61441081e5d7ff83d7770bc0b5f14f977fc
+  seccomp_profile: bundled:chromium-userns
+  cpus: 6
+caches:
+  - .nuget-packages
+premise_files:
+  - path: NuGet.Config
+    content: |
+      <configuration>
+        <config>
+          <add key="globalPackagesFolder" value=".nuget-packages" />
+        </config>
+      </configuration>
+gitignore_additions:
+  - bin/
+  - obj/
+  - node_modules/
+  - .nuget-packages/

agentic_dev_loop/core/profiles/data/python.yaml

@@ -0,0 +1,8 @@
+name: python
+engine_min: 0.9.2
+description: Python project; the sandbox builds its own venv per run
+isolation:
+  image: ghcr.io/lukedawilson/agentic-dev-loop/dev@sha256:890105209c127446caf20ce3dc05f0c0f5527e9d679e18cc0075e6b0ee917434
+  cpus: 2
+gitignore_additions:
+  - .venv-sandbox/

agentic_dev_loop/engine/cli.py

@@ -165,6 +165,12 @@ def main(argv: list[str] | None = None) -> int:
         argv = list(argv)
     if argv and argv[0] == "containers":
         return _run_containers(argv[1:])
+    if argv and argv[0] == "init":
+        from .onboarding.init import run_init
+        return run_init(argv[1:])
+    if argv and argv[0] == "doctor":
+        from .onboarding.doctor import run_doctor
+        return run_doctor(argv[1:])
     probe = argparse.ArgumentParser(add_help=False)
     probe.add_argument("pipeline", type=Path, nargs="?")
     _add_version_flag(probe)

agentic_dev_loop/engine/graph.py

@@ -177,11 +177,25 @@ def run_pipeline(cfg_path, args, *, viz_bus=None,
             sandbox.close()
 
 
+def _build_profile_llms(cfg) -> dict:
+    """054 (D7): build the LLM for each profile referenced by any step,
+    eagerly, so a missing api_key_env fails at run start, not mid-run.
+    Declared-but-unreferenced profiles are shape-validated at load; their
+    keys are not checked here."""
+    referenced = {step.llm for step in cfg.steps if step.llm is not None}
+    return {name: build_llm(cfg.llms[name]) for name in sorted(referenced)}
+
+
 def _run_pipeline(cfg, base, registry, state_dir, max_attempts, args, viz_bus,
                   sandbox, resolved_secrets, tooling_paths) -> tuple[bool, int]:
     export_root = getattr(sandbox, "export_root", None)
     engine_allowlist = resolve_engine_allowlist(registry, args)
+    # 054 (D7): build the default LLM plus one per profile referenced by any
+    # step, eagerly, so a missing api_key_env for a referenced profile fails
+    # at run start, not mid-run.
+    profile_llms = _build_profile_llms(cfg)
     runtime = Runtime(cfg=cfg, registry=registry, llm=build_llm(cfg.llm),
+                      llms=profile_llms,
                       agents_dir=base / cfg.agents_dir, state_dir=state_dir,
                       workspace=Path.cwd(), sandbox=sandbox,
                       sandbox_cwd=Path(export_root) if export_root else None,

agentic_dev_loop/engine/hostboundary.py

@@ -32,6 +32,8 @@ if TYPE_CHECKING:
 # the dogfood pipeline and the consumer repo use); the other tooling paths are config- or
 # pipeline-file-relative.
 TOOLING_DIR_NAMES = ("aidlc-docs", "tools")
+TOOLING_FILE_NAMES = ("trigger-agentic-dev-loop.sh",
+                      "agentic-dev-loop/.engine-version")
 
 
 class HostBoundaryError(RuntimeError):
@@ -73,6 +75,7 @@ def tooling_rel_paths(cfg: "PipelineConfig", pipeline_path: str | Path,
         (base / cfg.agents_dir).resolve(),
         *((base / rel).resolve() for rel in cfg.additional_files),
         *(ws / name for name in TOOLING_DIR_NAMES),
+        *(ws / name for name in TOOLING_FILE_NAMES),
     ]
     rels = {p.relative_to(ws).as_posix() for p in candidates
             if p.is_relative_to(ws)}

agentic_dev_loop/engine/llm.py

@@ -4,64 +4,98 @@ never fall back to another env var (no silent fallbacks)."""
 import os
 
 from openhands.sdk import LLM
-from openhands.sdk.llm.utils import model_features as _model_features
 
 from agentic_dev_loop.core.config import LlmConfig
 
-# Compat shim: OpenHands SDK 1.17 gates reasoning_content passback on a closed
-# model-name list (SEND_REASONING_CONTENT_MODELS) that does not know
-# deepseek-v4-pro. DeepSeek's thinking mode 400s on any multi-turn request
-# whose history omits prior reasoning_content. Unlike force_string_serializer,
-# the SDK exposes no instance-level override, so register the model here.
-# Remove once the SDK lists the model or adds an override.
-_DEEPSEEK_MODEL = "deepseek-v4-pro"
-if _DEEPSEEK_MODEL not in _model_features.SEND_REASONING_CONTENT_MODELS:
-    _model_features.SEND_REASONING_CONTENT_MODELS.append(_DEEPSEEK_MODEL)
-
-# Compat shim 2: the SDK splits a multi-tool-call turn into one assistant
-# message per call (Agent.step) and carries reasoning_content only on the
-# first; Message.to_chat_dict also drops empty-string reasoning. DeepSeek's
-# thinking mode 400s any request whose history contains reasoning_content
-# but omits it from an assistant tool-call message ("The reasoning_content
-# in the thinking mode must be passed back to the API"). Repair the
-# serialized history: an assistant tool-call message without its own
-# reasoning borrows the turn's last reasoning (reset on user turns), and a
-# present-but-empty reasoning is still written (field presence matters).
-# Remove once the SDK distributes reasoning_content to every message.
+# 054 (D8): reasoning passback is config-gated, never name-list-gated. The
+# SDK gates reasoning_content passback on a closed model-name list
+# (SEND_REASONING_CONTENT_MODELS) the engine never consults; instead each
+# LLM instance carries the engine-resolved effort on
+# ``_agentic_dev_loop_reasoning_effort`` and the serializer below gates
+# passback on it. Gate on = the effort is set and not "none"; gate off =
+# reasoning is stripped and, when history still carries reasoning_content,
+# a clear engine error fires before the doomed request is sent (D12).
 _ORIGINAL_FORMAT_MESSAGES = LLM.format_messages_for_llm
+
+
+def _reasoning_gate_on(llm: LLM) -> bool:
+    """The engine-configured effort for this instance, if any. The SDK's own
+    ``reasoning_effort`` field defaults to "high", so a direct (non-engine)
+    instance would read as gate-on; the dedicated attribute is only set by
+    ``build_llm``, keeping absent effort = reasoning off."""
+    effort = getattr(llm, "_agentic_dev_loop_reasoning_effort", None)
+    return effort is not None and effort != "none"
+
+
+def _reasoning_stripped_error(llm: LLM) -> RuntimeError:
+    """054 (D12): gate off while the conversation still carries
+    reasoning_content - a request that strips it would 400 at the provider."""
+    effort = getattr(llm, "_agentic_dev_loop_reasoning_effort", None)
+    return RuntimeError(
+        f"model {llm.model!r} is configured with reasoning off "
+        f"(reasoning_effort={effort!r}) but the conversation history carries "
+        "reasoning_content that would be stripped from the request. Set "
+        "'reasoning_effort' (low/medium/high/xhigh) on the step or its llm "
+        "profile, use 'none' only where the provider honors it, or use a "
+        "non-thinking model."
+    )
+
+
 if not getattr(_ORIGINAL_FORMAT_MESSAGES, "_agentic_dev_loop_reasoning_repair", False):
-    def _repair_reasoning_passback(self, messages: list) -> list[dict]:
+    def _config_gated_reasoning_serializer(self, messages: list) -> list[dict]:
+        """The engine-owned reasoning passback serializer (054 D8).
+
+        Gate on: every assistant message that carries reasoning_content
+        writes it back (the SDK only does so for listed models and only on
+        the first message of a split tool-call turn), and a tool-call
+        message without its own reasoning borrows the turn's last reasoning
+        (reset on user turns). Gate off: reasoning is stripped from the
+        outgoing request and, if history still carries reasoning_content,
+        the D12 error fires instead of sending a doomed request.
+        """
         out = _ORIGINAL_FORMAT_MESSAGES(self, messages)
+        if not _reasoning_gate_on(self):
+            for d in out:
+                d.pop("reasoning_content", None)
+            if any(getattr(m, "reasoning_content", None) for m in messages):
+                raise _reasoning_stripped_error(self)
+            return out
+
         last = None
         for msg, d in zip(messages, out):
             if msg.role == "user":
                 last = None
-            if msg.role == "assistant" and msg.tool_calls:
-                rc = getattr(msg, "reasoning_content", None)
+                continue
+            if msg.role != "assistant":
+                continue
+            rc = getattr(msg, "reasoning_content", None)
+            if msg.tool_calls:
                 if rc is not None:
                     last = rc
                 if last is not None:
                     d["reasoning_content"] = last
+            elif rc:
+                d["reasoning_content"] = rc
         return out
 
-    _repair_reasoning_passback._agentic_dev_loop_reasoning_repair = True
-    LLM.format_messages_for_llm = _repair_reasoning_passback
+    _config_gated_reasoning_serializer._agentic_dev_loop_reasoning_repair = True
+    LLM.format_messages_for_llm = _config_gated_reasoning_serializer
 
 
 def build_llm(cfg: LlmConfig, reasoning_effort: str | None = None) -> LLM:
     api_key = os.environ.get(cfg.api_key_env)
     if not api_key:
         raise RuntimeError(f"{cfg.api_key_env} environment variable is required")
-    # 047 (D2/D7): an explicit per-step override wins, else the llm block's
-    # value applies, else the field is omitted entirely and the SDK default
-    # ("high") is in force. The reasoning_content shims above stay untouched.
+    # 054 (D6): a step's value wins, else the effective profile's value, else
+    # off. reasoning_effort is always passed (None when unset) so the SDK
+    # "high" default cannot engage; absent effort = reasoning off.
     effort = reasoning_effort if reasoning_effort is not None else cfg.reasoning_effort
-    kwargs = {
-        "model": cfg.model,
-        "api_key": api_key,
-        "base_url": cfg.base_url,
-        "timeout": cfg.timeout,  # policy: no LLM timeout unless explicitly set
-    }
-    if effort is not None:
-        kwargs["reasoning_effort"] = effort
-    return LLM(**kwargs)
+    llm = LLM(
+        model=cfg.model,
+        api_key=api_key,
+        base_url=cfg.base_url,
+        timeout=cfg.timeout,  # policy: no LLM timeout unless explicitly set
+        reasoning_effort=effort,
+    )
+    llm._agentic_dev_loop_reasoning_effort = effort
+    return llm

agentic_dev_loop/engine/onboarding/__init__.py

@@ -0,0 +1,6 @@
+"""Consumer onboarding: init, doctor, recipes, and templates.
+
+These modules are engine concerns (they render pipelines and probe the host);
+the only core dependency is ``agentic_dev_loop.core.profiles``, the allowed
+engineering direction.
+"""