agentic-dev-loop 0.9.2__tar.gz → 0.10.0__tar.gz

{agentic_dev_loop-0.9.2/src/agentic_dev_loop.egg-info → agentic_dev_loop-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 0.9.2
+Version: 0.10.0
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -202,6 +202,17 @@ llm:
   api_key_env: OPENAI_API_KEY
   # reasoning_effort: medium                        # optional: low | medium | high | xhigh | none
 
+# Named LLM profiles (054): a step names one with `llm: <name>` to move the
+# whole profile (model, endpoint, key, effort default) together - no partial
+# merges. The `llm:` block above remains the default. Profile keys are
+# host-side: sandbox access still goes through `secrets:`, never a profile key.
+# llms:
+#   review:
+#     model: openai/deepseek-v4-pro
+#     base_url: https://api.deepseek.com
+#     api_key_env: REVIEW_API_KEY
+#     reasoning_effort: xhigh
+
 max_attempts: 10                                        # CLI --max-attempts overrides
 agents_dir: sdk_agents                                  # your <name>.agent.md files
 
@@ -231,7 +242,8 @@ steps:
     agent: review
     artifact: review-findings.md
     verdicts: { pass: APPROVED, fail: NEEDS CHANGES }
-    # reasoning_effort: xhigh                        # per-step override; falls back to the llm block, then SDK default
+    # reasoning_effort: xhigh                        # per-step override of the effective profile's effort
+    # llm: review                                    # (054) select a named `llms:` profile for this step
     on_pass: qa
     on_fail: { goto: dev, retry: true }
 
@@ -257,7 +269,8 @@ steps:
 | `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
 | `custom_prompt:` | Planned (planning-docs/040). Optional agent-step value: literal text, or a path whose file contents are read at load time, appended verbatim to the agent prompt at context assembly (after the prompt, before the task/artifacts). A value that looks like a path but names no file is a validation error. Agent steps only. |
-| `reasoning_effort:` | Optional `low` / `medium` / `high` / `xhigh` / `none`. Set on the `llm` block (pipeline-global) or per-step (overrides the block). Unset anywhere = the field is not passed and the SDK default (`high`) applies, so today's behavior is unchanged. Forwarded only for models the SDK/LiteLLM mark as supporting it; an unsupported value fails at the first LLM call. See [Reasoning effort](#reasoning-effort-opt-in). |
+| `llms:` (top-level) / step `llm:` | Named LLM profiles, each a full `LlmConfig` (`model`, `base_url`, `api_key_env`, `timeout`, `reasoning_effort`). A step names one with `llm: <profile-name>`; the whole profile moves together (no partial merges). Allowed only on agent and brief steps. The top-level `llm:` block remains the default. Profile keys are host-side - sandbox access still goes through `secrets:`. |
+| `reasoning_effort:` | Optional `low` / `medium` / `high` / `xhigh` / `none`. Set on the `llm` block, a `llms:` profile, or per-step (a step value overrides the effective profile's). Unset anywhere = reasoning off: nothing is forwarded and reasoning is stripped from requests. A thinking model without an effort level is invalid config and fails at the first request (crap in, crap out). See [Reasoning effort](#reasoning-effort-opt-in). |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` runs fresh at every step boundary in a one-shot provision container targeting the export (command or agent steps; network ON; no stamping); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
 | `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |
@@ -272,17 +285,25 @@ steps:
 
 ### Reasoning effort (opt-in)
 
-`reasoning_effort` is an opt-in latency dial on the pipeline `llm` block and
-on individual agent steps. It takes one of `low`, `medium`, `high`, `xhigh`,
-or `none`; unset means the field is never passed and the SDK default
-(`high`) applies, so a pipeline that omits it behaves exactly as before. A
-step's value overrides the `llm` block's value, so the review lane can hold
-a higher effort than the rest.
-
-The value is forwarded only for models the SDK/LiteLLM mark as supporting
-it; an unsupported value fails at the first LLM call (the schema rejects
-unknown names at load time, but cannot know provider capability). No
-pipeline ships a value: adopt one only after an observed run proves lower
+`reasoning_effort` is an opt-in latency dial on the pipeline `llm` block, a
+named `llms:` profile, and individual agent steps. It takes one of `low`,
+`medium`, `high`, `xhigh`, or `none`; unset means reasoning is off - the
+field is forwarded as none, reasoning is stripped from requests, and a
+thinking model whose history still carries reasoning fails fast with an
+actionable engine error rather than a provider 400. A step's value overrides
+the effective profile's value, so the review lane can hold a higher effort
+than the rest, or a named profile can move an entire lane to a different
+provider.
+
+Reasoning is opt-in and provider-generic: any openai-compatible endpoint
+expressible as an `LlmConfig` works, and reasoning passback is gated on the
+configured effort level, never on a model-name list. A thinking model without
+an effort level (or with `none` where the provider ignores it) is invalid
+config - it still reasons but its API requires the passback the engine strips,
+so the engine raises before the doomed request is sent. Set
+`reasoning_effort` on the step or its profile, or use a non-thinking model.
+The schema rejects unknown effort names at load time, but cannot know provider
+capability; adopt an effort value only after an observed run proves lower
 per-turn latency with a green suite and no provider 400s.
 
 Recommended lane defaults (guidance only, not enforced):
@@ -515,22 +536,23 @@ adapt per repo.
 Adaptation checklist for a new repo:
 
 1. `llm:` - model, `base_url`, `api_key_env`.
-2. `isolation:` - toolchain image override (the consumer repo pins a
+2. `llms:` (optional) - named profiles for multi-provider lanes (keep review on the strongest model); a step opts in with `llm: <name>`.
+3. `isolation:` - toolchain image override (the consumer repo pins a
    toolchain image by digest) and `seccomp_profile: bundled:chromium-userns`
    only if a stage runs Chromium.
-3. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
+4. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
    (`.nuget-packages`, `qa/node_modules`, `qa/.browsers`,
    `frontend-editor/node_modules`); caches are never synced back, and a
    step's `setup:` hook runs with them mounted so it can warm them.
-4. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
-5. `secrets:` - refs only, resolved from host env; each step opts in to the
+5. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
+6. `secrets:` - refs only, resolved from host env; each step opts in to the
    refs it needs.
-6. `egress:` - `presets: [package-registries]` for fetch steps;
+7. `egress:` - `presets: [package-registries]` for fetch steps;
    `class: browser` (broad-but-logged) for browser-tier qa only.
-7. `deps_policy:` and `lockfiles:` - see
+8. `deps_policy:` and `lockfiles:` - see
    [Dependency policy](#dependency-policy-locked-by-default).
-8. The dev prompt's impossible set - write it for your toolchain.
-9. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
+9. The dev prompt's impossible set - write it for your toolchain.
+10. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
    docs: shared context for every agent step.
 
 Validate before the first run - dry-run loads and prints the resolved plan

{agentic_dev_loop-0.9.2 → agentic_dev_loop-0.10.0}/README.md

@@ -158,6 +158,17 @@ llm:
   api_key_env: OPENAI_API_KEY
   # reasoning_effort: medium                        # optional: low | medium | high | xhigh | none
 
+# Named LLM profiles (054): a step names one with `llm: <name>` to move the
+# whole profile (model, endpoint, key, effort default) together - no partial
+# merges. The `llm:` block above remains the default. Profile keys are
+# host-side: sandbox access still goes through `secrets:`, never a profile key.
+# llms:
+#   review:
+#     model: openai/deepseek-v4-pro
+#     base_url: https://api.deepseek.com
+#     api_key_env: REVIEW_API_KEY
+#     reasoning_effort: xhigh
+
 max_attempts: 10                                        # CLI --max-attempts overrides
 agents_dir: sdk_agents                                  # your <name>.agent.md files
 
@@ -187,7 +198,8 @@ steps:
     agent: review
     artifact: review-findings.md
     verdicts: { pass: APPROVED, fail: NEEDS CHANGES }
-    # reasoning_effort: xhigh                        # per-step override; falls back to the llm block, then SDK default
+    # reasoning_effort: xhigh                        # per-step override of the effective profile's effort
+    # llm: review                                    # (054) select a named `llms:` profile for this step
     on_pass: qa
     on_fail: { goto: dev, retry: true }
 
@@ -213,7 +225,8 @@ steps:
 | `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
 | `custom_prompt:` | Planned (planning-docs/040). Optional agent-step value: literal text, or a path whose file contents are read at load time, appended verbatim to the agent prompt at context assembly (after the prompt, before the task/artifacts). A value that looks like a path but names no file is a validation error. Agent steps only. |
-| `reasoning_effort:` | Optional `low` / `medium` / `high` / `xhigh` / `none`. Set on the `llm` block (pipeline-global) or per-step (overrides the block). Unset anywhere = the field is not passed and the SDK default (`high`) applies, so today's behavior is unchanged. Forwarded only for models the SDK/LiteLLM mark as supporting it; an unsupported value fails at the first LLM call. See [Reasoning effort](#reasoning-effort-opt-in). |
+| `llms:` (top-level) / step `llm:` | Named LLM profiles, each a full `LlmConfig` (`model`, `base_url`, `api_key_env`, `timeout`, `reasoning_effort`). A step names one with `llm: <profile-name>`; the whole profile moves together (no partial merges). Allowed only on agent and brief steps. The top-level `llm:` block remains the default. Profile keys are host-side - sandbox access still goes through `secrets:`. |
+| `reasoning_effort:` | Optional `low` / `medium` / `high` / `xhigh` / `none`. Set on the `llm` block, a `llms:` profile, or per-step (a step value overrides the effective profile's). Unset anywhere = reasoning off: nothing is forwarded and reasoning is stripped from requests. A thinking model without an effort level is invalid config and fails at the first request (crap in, crap out). See [Reasoning effort](#reasoning-effort-opt-in). |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` runs fresh at every step boundary in a one-shot provision container targeting the export (command or agent steps; network ON; no stamping); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
 | `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |
@@ -228,17 +241,25 @@ steps:
 
 ### Reasoning effort (opt-in)
 
-`reasoning_effort` is an opt-in latency dial on the pipeline `llm` block and
-on individual agent steps. It takes one of `low`, `medium`, `high`, `xhigh`,
-or `none`; unset means the field is never passed and the SDK default
-(`high`) applies, so a pipeline that omits it behaves exactly as before. A
-step's value overrides the `llm` block's value, so the review lane can hold
-a higher effort than the rest.
-
-The value is forwarded only for models the SDK/LiteLLM mark as supporting
-it; an unsupported value fails at the first LLM call (the schema rejects
-unknown names at load time, but cannot know provider capability). No
-pipeline ships a value: adopt one only after an observed run proves lower
+`reasoning_effort` is an opt-in latency dial on the pipeline `llm` block, a
+named `llms:` profile, and individual agent steps. It takes one of `low`,
+`medium`, `high`, `xhigh`, or `none`; unset means reasoning is off - the
+field is forwarded as none, reasoning is stripped from requests, and a
+thinking model whose history still carries reasoning fails fast with an
+actionable engine error rather than a provider 400. A step's value overrides
+the effective profile's value, so the review lane can hold a higher effort
+than the rest, or a named profile can move an entire lane to a different
+provider.
+
+Reasoning is opt-in and provider-generic: any openai-compatible endpoint
+expressible as an `LlmConfig` works, and reasoning passback is gated on the
+configured effort level, never on a model-name list. A thinking model without
+an effort level (or with `none` where the provider ignores it) is invalid
+config - it still reasons but its API requires the passback the engine strips,
+so the engine raises before the doomed request is sent. Set
+`reasoning_effort` on the step or its profile, or use a non-thinking model.
+The schema rejects unknown effort names at load time, but cannot know provider
+capability; adopt an effort value only after an observed run proves lower
 per-turn latency with a green suite and no provider 400s.
 
 Recommended lane defaults (guidance only, not enforced):
@@ -471,22 +492,23 @@ adapt per repo.
 Adaptation checklist for a new repo:
 
 1. `llm:` - model, `base_url`, `api_key_env`.
-2. `isolation:` - toolchain image override (the consumer repo pins a
+2. `llms:` (optional) - named profiles for multi-provider lanes (keep review on the strongest model); a step opts in with `llm: <name>`.
+3. `isolation:` - toolchain image override (the consumer repo pins a
    toolchain image by digest) and `seccomp_profile: bundled:chromium-userns`
    only if a stage runs Chromium.
-3. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
+4. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
    (`.nuget-packages`, `qa/node_modules`, `qa/.browsers`,
    `frontend-editor/node_modules`); caches are never synced back, and a
    step's `setup:` hook runs with them mounted so it can warm them.
-4. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
-5. `secrets:` - refs only, resolved from host env; each step opts in to the
+5. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
+6. `secrets:` - refs only, resolved from host env; each step opts in to the
    refs it needs.
-6. `egress:` - `presets: [package-registries]` for fetch steps;
+7. `egress:` - `presets: [package-registries]` for fetch steps;
    `class: browser` (broad-but-logged) for browser-tier qa only.
-7. `deps_policy:` and `lockfiles:` - see
+8. `deps_policy:` and `lockfiles:` - see
    [Dependency policy](#dependency-policy-locked-by-default).
-8. The dev prompt's impossible set - write it for your toolchain.
-9. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
+9. The dev prompt's impossible set - write it for your toolchain.
+10. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
    docs: shared context for every agent step.
 
 Validate before the first run - dry-run loads and prints the resolved plan

{agentic_dev_loop-0.9.2 → agentic_dev_loop-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "0.9.2"
+version = "0.10.0"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"

{agentic_dev_loop-0.9.2 → agentic_dev_loop-0.10.0}/src/agentic_dev_loop/core/config.py

@@ -396,9 +396,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 +490,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 +601,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 +620,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
@@ -690,6 +707,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.

{agentic_dev_loop-0.9.2 → agentic_dev_loop-0.10.0}/src/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-0.10.0/src/agentic_dev_loop/engine/llm.py

@@ -0,0 +1,101 @@
+"""LLM construction from pipeline config. Fail fast on a missing key -
+never fall back to another env var (no silent fallbacks)."""
+
+import os
+
+from openhands.sdk import LLM
+
+from agentic_dev_loop.core.config import LlmConfig
+
+# 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 _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
+                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
+
+    _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")
+    # 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
+    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-0.9.2 → agentic_dev_loop-0.10.0}/src/agentic_dev_loop/engine/stages.py

@@ -120,6 +120,9 @@ class Runtime:
     agents_dir: Path
     state_dir: Path
     workspace: Path
+    # 054 (D7): named-profile LLMs built eagerly at run start, keyed by the
+    # `llms:` profile name. `llm` above remains the default (`llm:` block).
+    llms: dict[str, "LLM"] = field(default_factory=dict)
     sandbox: Sandbox | None = None
     # unit-5: the .git-free export root sandboxed steps run in (BR-2); None =
     # the real workspace (no export materialised - fake/legacy paths).
@@ -176,13 +179,18 @@ class Runtime:
                              if step is not None else None),
                     forbidden_commands=forbidden_commands,
                     allowlist=allowlist)
-            # 047 (D7): a step's reasoning_effort overrides the llm block's;
-            # self.llm already carries the block value (or the SDK default),
-            # so only build a fresh LLM when the step overrides it.
+            # 054 (D6/D7): a named profile selects the whole config (model,
+            # endpoint, key, effort default move together); the step's own
+            # reasoning_effort then overrides the effective profile's value.
             llm = self.llm
-            if step is not None and step.reasoning_effort is not None:
-                llm = build_llm(self.cfg.llm,
-                                reasoning_effort=step.reasoning_effort)
+            if step is not None:
+                effective_cfg = (self.cfg.llms[step.llm]
+                                 if step.llm is not None else self.cfg.llm)
+                if step.llm is not None:
+                    llm = self.llms.get(step.llm, self.llm)
+                if step.reasoning_effort is not None:
+                    llm = build_llm(effective_cfg,
+                                    reasoning_effort=step.reasoning_effort)
             if step is not None and step.kind == "brief":
                 agent = load_brief_agent(
                     agent_name, step.brief_inputs.sections, llm)

{agentic_dev_loop-0.9.2 → agentic_dev_loop-0.10.0/src/agentic_dev_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 0.9.2
+Version: 0.10.0
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -202,6 +202,17 @@ llm:
   api_key_env: OPENAI_API_KEY
   # reasoning_effort: medium                        # optional: low | medium | high | xhigh | none
 
+# Named LLM profiles (054): a step names one with `llm: <name>` to move the
+# whole profile (model, endpoint, key, effort default) together - no partial
+# merges. The `llm:` block above remains the default. Profile keys are
+# host-side: sandbox access still goes through `secrets:`, never a profile key.
+# llms:
+#   review:
+#     model: openai/deepseek-v4-pro
+#     base_url: https://api.deepseek.com
+#     api_key_env: REVIEW_API_KEY
+#     reasoning_effort: xhigh
+
 max_attempts: 10                                        # CLI --max-attempts overrides
 agents_dir: sdk_agents                                  # your <name>.agent.md files
 
@@ -231,7 +242,8 @@ steps:
     agent: review
     artifact: review-findings.md
     verdicts: { pass: APPROVED, fail: NEEDS CHANGES }
-    # reasoning_effort: xhigh                        # per-step override; falls back to the llm block, then SDK default
+    # reasoning_effort: xhigh                        # per-step override of the effective profile's effort
+    # llm: review                                    # (054) select a named `llms:` profile for this step
     on_pass: qa
     on_fail: { goto: dev, retry: true }
 
@@ -257,7 +269,8 @@ steps:
 | `terminal_timeout:` | Optional agent-step per-action timeout in seconds (gt 0). `SandboxTerminalExecutor` uses it when the agent leaves the terminal action timeout unset, overriding the SDK tool's default. `None` = current behavior. |
 | `finalize_nudge_turns:` | Optional agent-step final-response nudge (gt 0). Requires `max_iterations:` and must be less than it. At `max_iterations - finalize_nudge_turns` completed turns the engine injects one advisory turn ("`N turns remain: produce your final response now`"), exactly once; the agent may still exhaust its turns and existing stuck/unclear handling applies unchanged. Absent = current behavior. Provisional pending one consumer run (revert if noisy or the raised cap inflates cost). |
 | `custom_prompt:` | Planned (planning-docs/040). Optional agent-step value: literal text, or a path whose file contents are read at load time, appended verbatim to the agent prompt at context assembly (after the prompt, before the task/artifacts). A value that looks like a path but names no file is a validation error. Agent steps only. |
-| `reasoning_effort:` | Optional `low` / `medium` / `high` / `xhigh` / `none`. Set on the `llm` block (pipeline-global) or per-step (overrides the block). Unset anywhere = the field is not passed and the SDK default (`high`) applies, so today's behavior is unchanged. Forwarded only for models the SDK/LiteLLM mark as supporting it; an unsupported value fails at the first LLM call. See [Reasoning effort](#reasoning-effort-opt-in). |
+| `llms:` (top-level) / step `llm:` | Named LLM profiles, each a full `LlmConfig` (`model`, `base_url`, `api_key_env`, `timeout`, `reasoning_effort`). A step names one with `llm: <profile-name>`; the whole profile moves together (no partial merges). Allowed only on agent and brief steps. The top-level `llm:` block remains the default. Profile keys are host-side - sandbox access still goes through `secrets:`. |
+| `reasoning_effort:` | Optional `low` / `medium` / `high` / `xhigh` / `none`. Set on the `llm` block, a `llms:` profile, or per-step (a step value overrides the effective profile's). Unset anywhere = reasoning off: nothing is forwarded and reasoning is stripped from requests. A thinking model without an effort level is invalid config and fails at the first request (crap in, crap out). See [Reasoning effort](#reasoning-effort-opt-in). |
 | `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
 | `env:` / `setup:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` runs fresh at every step boundary in a one-shot provision container targeting the export (command or agent steps; network ON; no stamping); `network: true` lets a command/agent step reach the hosts its `egress:` allowlist names (default off) - see [Per-stage networking](#per-stage-networking). |
 | `mounts:` / `egress:` | Per-step workspace isolation. `mounts:` lists `{path, mode}` entries (`rw`/`ro`, default `ro`) and is **strict-by-default** - empty/missing mounts nothing; only declared-rw paths sync back to the repo. `egress:` is `{class, presets, targets}` (`class: browser` = broad-but-logged; otherwise a strict allowlist). See [Per-stage networking](#per-stage-networking) and [docs/setup.md](docs/setup.md). |
@@ -272,17 +285,25 @@ steps:
 
 ### Reasoning effort (opt-in)
 
-`reasoning_effort` is an opt-in latency dial on the pipeline `llm` block and
-on individual agent steps. It takes one of `low`, `medium`, `high`, `xhigh`,
-or `none`; unset means the field is never passed and the SDK default
-(`high`) applies, so a pipeline that omits it behaves exactly as before. A
-step's value overrides the `llm` block's value, so the review lane can hold
-a higher effort than the rest.
-
-The value is forwarded only for models the SDK/LiteLLM mark as supporting
-it; an unsupported value fails at the first LLM call (the schema rejects
-unknown names at load time, but cannot know provider capability). No
-pipeline ships a value: adopt one only after an observed run proves lower
+`reasoning_effort` is an opt-in latency dial on the pipeline `llm` block, a
+named `llms:` profile, and individual agent steps. It takes one of `low`,
+`medium`, `high`, `xhigh`, or `none`; unset means reasoning is off - the
+field is forwarded as none, reasoning is stripped from requests, and a
+thinking model whose history still carries reasoning fails fast with an
+actionable engine error rather than a provider 400. A step's value overrides
+the effective profile's value, so the review lane can hold a higher effort
+than the rest, or a named profile can move an entire lane to a different
+provider.
+
+Reasoning is opt-in and provider-generic: any openai-compatible endpoint
+expressible as an `LlmConfig` works, and reasoning passback is gated on the
+configured effort level, never on a model-name list. A thinking model without
+an effort level (or with `none` where the provider ignores it) is invalid
+config - it still reasons but its API requires the passback the engine strips,
+so the engine raises before the doomed request is sent. Set
+`reasoning_effort` on the step or its profile, or use a non-thinking model.
+The schema rejects unknown effort names at load time, but cannot know provider
+capability; adopt an effort value only after an observed run proves lower
 per-turn latency with a green suite and no provider 400s.
 
 Recommended lane defaults (guidance only, not enforced):
@@ -515,22 +536,23 @@ adapt per repo.
 Adaptation checklist for a new repo:
 
 1. `llm:` - model, `base_url`, `api_key_env`.
-2. `isolation:` - toolchain image override (the consumer repo pins a
+2. `llms:` (optional) - named profiles for multi-provider lanes (keep review on the strongest model); a step opts in with `llm: <name>`.
+3. `isolation:` - toolchain image override (the consumer repo pins a
    toolchain image by digest) and `seccomp_profile: bundled:chromium-userns`
    only if a stage runs Chromium.
-3. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
+4. `caches:` - toolchain cache dirs as rw bind-mounts shared across runs
    (`.nuget-packages`, `qa/node_modules`, `qa/.browsers`,
    `frontend-editor/node_modules`); caches are never synced back, and a
    step's `setup:` hook runs with them mounted so it can warm them.
-4. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
-5. `secrets:` - refs only, resolved from host env; each step opts in to the
+5. `sync_excludes:` - build output trees (`**/bin/**`, `**/obj/**`).
+6. `secrets:` - refs only, resolved from host env; each step opts in to the
    refs it needs.
-6. `egress:` - `presets: [package-registries]` for fetch steps;
+7. `egress:` - `presets: [package-registries]` for fetch steps;
    `class: browser` (broad-but-logged) for browser-tier qa only.
-7. `deps_policy:` and `lockfiles:` - see
+8. `deps_policy:` and `lockfiles:` - see
    [Dependency policy](#dependency-policy-locked-by-default).
-8. The dev prompt's impossible set - write it for your toolchain.
-9. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
+9. The dev prompt's impossible set - write it for your toolchain.
+10. `additional_files:` - the repo's `AGENTS.md`, coding standards, design
    docs: shared context for every agent step.
 
 Validate before the first run - dry-run loads and prints the resolved plan