agentic-dev-loop 1.0.0a8__tar.gz → 1.0.0a9__tar.gz

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a8
+Version: 1.0.0a9
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -192,9 +192,49 @@ steps:
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `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:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
+| `secrets:` (top-level) / step `secrets:` | Declares secret **refs only — never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
 
+### Secrets (`secrets:`) — refs only, never values
+
+Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.
+Declare the refs at the top level and opt each step into the refs it needs:
+
+```yaml
+secrets:                              # refs only — never values
+  kinde-client-secret:                # ref name (arbitrary)
+    from: env                         # provider name
+    key: KINDIE_CLIENT_SECRET         # provider-specific locator
+  r2-keys:
+    from: env
+    key: YOSK_R2_KEYS
+
+steps:
+  - name: qa
+    agent: qa
+    secrets: [kinde-client-secret, r2-keys]
+```
+
+- The engine resolves every declared ref **host-side at run start** (the `env`
+  provider reads the named host environment variable). A missing variable, an
+  unknown provider, or a ref a step lists without declaring it fails fast —
+  naming the ref, the step, and the provider error. No silent fallback.
+- A resolved secret is injected into a step's exec env **only when that step
+  lists the ref** — the same path step `env:` uses, no new channel. The secret
+  never reaches the provision container, `state_dir`, or any other step.
+- Prefer a mechanical `command` step for secret-consuming work (a script runs
+  the app with creds) so the LLM and the secret never meet; an `agent` step
+  holds a secret only when its job genuinely requires it.
+- **`.env*` ban.** At run start the workspace root is scanned for `.env*`
+  files. Any hit fails fast, naming the files, with the remedy text. The
+  convention fixtures `.env.example`, `.env.template`, and `.env.sample` are
+  whitelisted. This applies regardless of `network:` flags.
+- **Output scrubbing.** Resolved secret values are scrubbed from every
+  engine-written output — captured step output, retry notes, artifacts, and
+  `state_dir` files. (Hygiene: the declaring step's agent has already seen
+  the value in its own env.)
+
 ### Per-stage networking
 
 The sandbox is network-off by default. A step that legitimately needs egress —
@@ -226,8 +266,7 @@ steps:
 git clone git@github.com:lukedawilson/agentic-dev-loop.git
 cd agentic-dev-loop
 ./setup-venv.sh                       # idempotent .venv setup (never touches bare pip)
-# create .env with your LLM key (loaded by trigger-agentic-dev-loop.sh, never committed):
-#   echo 'OPENAI_API_KEY=...' > .env
+export OPENAI_API_KEY=...           # set your LLM key in the host env (no .env in the repo)
 python -m pytest tests/ -q            # fast suite
 python -m pytest tests/ -q -m "not docker"   # skip engine-dependent tests
 ./trigger-agentic-dev-loop.sh --dry-run      # run the shipped pipeline against this repo

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/README.md

@@ -153,9 +153,49 @@ steps:
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `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:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
+| `secrets:` (top-level) / step `secrets:` | Declares secret **refs only — never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
 
+### Secrets (`secrets:`) — refs only, never values
+
+Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.
+Declare the refs at the top level and opt each step into the refs it needs:
+
+```yaml
+secrets:                              # refs only — never values
+  kinde-client-secret:                # ref name (arbitrary)
+    from: env                         # provider name
+    key: KINDIE_CLIENT_SECRET         # provider-specific locator
+  r2-keys:
+    from: env
+    key: YOSK_R2_KEYS
+
+steps:
+  - name: qa
+    agent: qa
+    secrets: [kinde-client-secret, r2-keys]
+```
+
+- The engine resolves every declared ref **host-side at run start** (the `env`
+  provider reads the named host environment variable). A missing variable, an
+  unknown provider, or a ref a step lists without declaring it fails fast —
+  naming the ref, the step, and the provider error. No silent fallback.
+- A resolved secret is injected into a step's exec env **only when that step
+  lists the ref** — the same path step `env:` uses, no new channel. The secret
+  never reaches the provision container, `state_dir`, or any other step.
+- Prefer a mechanical `command` step for secret-consuming work (a script runs
+  the app with creds) so the LLM and the secret never meet; an `agent` step
+  holds a secret only when its job genuinely requires it.
+- **`.env*` ban.** At run start the workspace root is scanned for `.env*`
+  files. Any hit fails fast, naming the files, with the remedy text. The
+  convention fixtures `.env.example`, `.env.template`, and `.env.sample` are
+  whitelisted. This applies regardless of `network:` flags.
+- **Output scrubbing.** Resolved secret values are scrubbed from every
+  engine-written output — captured step output, retry notes, artifacts, and
+  `state_dir` files. (Hygiene: the declaring step's agent has already seen
+  the value in its own env.)
+
 ### Per-stage networking
 
 The sandbox is network-off by default. A step that legitimately needs egress —
@@ -187,8 +227,7 @@ steps:
 git clone git@github.com:lukedawilson/agentic-dev-loop.git
 cd agentic-dev-loop
 ./setup-venv.sh                       # idempotent .venv setup (never touches bare pip)
-# create .env with your LLM key (loaded by trigger-agentic-dev-loop.sh, never committed):
-#   echo 'OPENAI_API_KEY=...' > .env
+export OPENAI_API_KEY=...           # set your LLM key in the host env (no .env in the repo)
 python -m pytest tests/ -q            # fast suite
 python -m pytest tests/ -q -m "not docker"   # skip engine-dependent tests
 ./trigger-agentic-dev-loop.sh --dry-run      # run the shipped pipeline against this repo

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/pyproject.toml

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

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/src/agentic_dev_loop/core/config.py

@@ -11,6 +11,7 @@ import yaml
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 TERMINALS = frozenset({"success", "failure"})
+KNOWN_SECRET_PROVIDERS = frozenset({"env"})
 
 
 class VerdictSpec(BaseModel):
@@ -36,6 +37,34 @@ def route_target(route: RouteTarget | None) -> str | None:
     return route.goto if isinstance(route, Route) else route
 
 
+class SecretSpec(BaseModel):
+    """One ``secrets:`` ref — the locator only, never a value. ``from`` names
+    the provider (``env`` first); ``key`` is that provider's locator (for
+    ``env``, the host environment variable to read and the step env name to
+    inject). Unknown keys fail at load (extra="forbid")."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    from_: str = Field(alias="from")
+    key: str
+
+    @field_validator("from_")
+    @classmethod
+    def _known_provider(cls, v: str) -> str:
+        if v not in KNOWN_SECRET_PROVIDERS:
+            raise ValueError(
+                f"unknown secret provider {v!r} (known: "
+                f"{sorted(KNOWN_SECRET_PROVIDERS)})")
+        return v
+
+    @field_validator("key")
+    @classmethod
+    def _nonempty_key(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("secret key must be a non-empty string")
+        return v
+
+
 class IsolationConfig(BaseModel):
     """Optional `isolation:` section — configures the always-on sandbox (BR-2).
     Absence means opinionated defaults, never unsandboxed behaviour. Unknown
@@ -86,6 +115,7 @@ class StepConfig(BaseModel):
     env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
     setup: str | None = None  # BR-13: command steps only
     network: bool = False  # per-stage egress (command + agent steps; action steps reject)
+    secrets: list[str] = []  # declared ref names; action steps reject
     on_pass: RouteTarget | None = None
     on_fail: RouteTarget | None = None
 
@@ -148,6 +178,11 @@ class StepConfig(BaseModel):
                 f"step {self.name!r}: 'network' is only allowed on 'agent' or "
                 "'command' steps"
             )
+        if self.secrets and self.action is not None:
+            raise ValueError(
+                f"step {self.name!r}: 'secrets' is only allowed on 'agent' or "
+                "'command' steps"
+            )
         return self
 
 
@@ -170,10 +205,28 @@ class PipelineConfig(BaseModel):
     llm: 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
     max_attempts: int = 3
     agents_dir: str
     steps: list[StepConfig] = Field(min_length=1)
 
+    @field_validator("secrets", mode="before")
+    @classmethod
+    def _reject_value_shaped_refs(cls, v: Any) -> Any:
+        if v is None:
+            return {}
+        if not isinstance(v, dict):
+            raise ValueError(
+                "'secrets' must be a mapping of ref name to "
+                "{from: ..., key: ...}")
+        for name, spec in v.items():
+            if not isinstance(spec, dict):
+                raise ValueError(
+                    f"secret ref {name!r} must be a mapping "
+                    "{from: ..., key: ...}, not a literal value — secret "
+                    "values never belong in the pipeline yaml")
+        return v
+
     @model_validator(mode="after")
     def _check_graph(self) -> "PipelineConfig":
         names = [s.name for s in self.steps]
@@ -191,6 +244,12 @@ class PipelineConfig(BaseModel):
                     raise ValueError(
                         f"step {step.name!r}: unknown route target {target!r}"
                     )
+        for step in self.steps:
+            for ref in step.secrets:
+                if ref not in self.secrets:
+                    raise ValueError(
+                        f"step {step.name!r}: secret ref {ref!r} is not "
+                        "declared in the top-level 'secrets:' section")
         return self
 
 

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/src/agentic_dev_loop/engine/agents.py

@@ -110,13 +110,17 @@ class SandboxTerminalExecutor(ToolExecutor):
 def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None] | None = None,
                               workspace: str = "", pipeline: str | None = None,
                               step: str | None = None,
-                              network: bool = False) -> None:
+                              network: bool = False,
+                              secrets: dict[str, str] | None = None) -> None:
     """Per-run re-registration of the `terminal` name (KD-4): a callable
     factory that builds the SDK terminal with a `SandboxTerminalExecutor`.
-    Pipelines are sequential, so re-registering per agent step is safe."""
+    Pipelines are sequential, so re-registering per agent step is safe.
+
+    ``secrets`` (019) is the per-step resolved secret env, injected into the
+    terminal's exec env only for steps that declared the refs."""
     from openhands.sdk.tool import register_tool
 
-    resolved_env = resolve_sandbox_env(env)
+    resolved_env = resolve_sandbox_env(env, secrets=secrets)
 
     def factory(conv_state, **params):
         return TerminalTool.create(

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/src/agentic_dev_loop/engine/dryrun.py

@@ -17,6 +17,7 @@ from .loaders import resolve_docs
 from .isolation import (isolation_state_dir, resolve_effective_profile,
                         resolve_image_ref)
 from .registry import Registry, default_registry, load_extensions
+from .secrets import scan_env_files
 
 
 def _validate_agents(cfg: PipelineConfig, agents_dir: Path) -> None:
@@ -113,6 +114,7 @@ def dry_run(cfg_path, args, registry: Registry | None = None) -> int:
     cfg_path = Path(cfg_path)
     cfg = load_config(cfg_path)
     base = cfg_path.resolve().parent
+    scan_env_files(Path.cwd())
 
     if registry is None:
         registry = default_registry()

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/src/agentic_dev_loop/engine/graph.py

@@ -22,6 +22,7 @@ from agentic_dev_loop.core.config import load_config
 from .isolation import startup_sandbox
 from .llm import build_llm
 from .loaders import resolve_docs
+from .secrets import resolve_secrets, scan_env_files
 from .registry import Registry, default_registry, load_extensions
 from .stages import (Runtime, build_context, clear_attempt_artifacts,
                      make_action_node, make_agent_node, make_bump_node,
@@ -107,6 +108,11 @@ def run_pipeline(cfg_path, args, *, viz_bus=None,
     base = cfg_path.resolve().parent
     max_attempts = getattr(args, "max_attempts", None) or cfg.max_attempts
 
+    # 019: refuse secret-bearing workspace files and resolve declared secret
+    # refs host-side BEFORE any sandbox/LLM work — fail fast, loudly.
+    scan_env_files(Path.cwd())
+    resolved_secrets = resolve_secrets(cfg)
+
     if registry is None:
         registry = default_registry()
         load_extensions(cfg.extensions, registry)
@@ -122,16 +128,17 @@ def run_pipeline(cfg_path, args, *, viz_bus=None,
                                refresh=getattr(args, "refresh", False))
     try:
         return _run_pipeline(cfg, base, registry, state_dir, max_attempts,
-                             args, viz_bus, sandbox)
+                             args, viz_bus, sandbox, resolved_secrets)
     finally:
         sandbox.close()
 
 
 def _run_pipeline(cfg, base, registry, state_dir, max_attempts, args, viz_bus,
-                  sandbox) -> tuple[bool, int]:
+                  sandbox, resolved_secrets) -> tuple[bool, int]:
     runtime = Runtime(cfg=cfg, registry=registry, llm=build_llm(cfg.llm),
                       agents_dir=base / cfg.agents_dir, state_dir=state_dir,
-                      workspace=Path.cwd(), sandbox=sandbox)
+                      workspace=Path.cwd(), sandbox=sandbox,
+                      secrets=resolved_secrets)
     state_dir.mkdir(parents=True, exist_ok=True)
 
     resume = getattr(args, "resume", None)

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/src/agentic_dev_loop/engine/isolation.py

@@ -183,11 +183,17 @@ def resolve_effective_profile(isolation: IsolationConfig | None) -> EffectivePro
 
 
 def resolve_sandbox_env(step_env: dict[str, str | None] | None, *,
-                        host_env: Mapping[str, str] | None = None) -> dict[str, str]:
+                        host_env: Mapping[str, str] | None = None,
+                        secrets: Mapping[str, str] | None = None) -> dict[str, str]:
     """Fixed safe base (PATH/HOME/LANG/LC_ALL/TERM) + the step's declared
     ``env:`` mapping only. A declared value of ``None`` inherits the host
     value; the global ``env_allowlist`` is never consulted and the LLM key is
-    never auto-added (NFR-3.1 / BR-9)."""
+    never auto-added (NFR-3.1 / BR-9).
+
+    ``secrets`` (019) carries the per-step resolved secret env — injected last,
+    so a declared ref is authoritative over any same-named ``env:`` entry. It
+    arrives only from ``step_secret_env``, which maps only the refs the step
+    declared, so no secret ever reaches an undeclaring step."""
     source = os.environ if host_env is None else host_env
     env = dict(SANDBOX_ENV_BASE)
     for name, value in (step_env or {}).items():
@@ -196,6 +202,8 @@ def resolve_sandbox_env(step_env: dict[str, str | None] | None, *,
                 env[name] = source[name]
         else:
             env[name] = value
+    for name, value in (secrets or {}).items():
+        env[name] = value
     return env
 
 

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/src/agentic_dev_loop/engine/outputs.py

@@ -16,6 +16,7 @@ from pathlib import Path
 from openhands.sdk.conversation.response_utils import get_agent_final_response
 
 from agentic_dev_loop.core.results import Result
+from .secrets import redact_values
 
 
 class CaptureError(enum.Enum):
@@ -32,11 +33,13 @@ class CapturedOutput:
 
     @staticmethod
     def from_agent_result(
-        conv, artifact: str, state_dir: Path
+        conv, artifact: str, state_dir: Path,
+        redactions: tuple[str, ...] = ()
     ) -> "Result[CapturedOutput, CaptureError]":
         text = _final_agent_text(conv)
         if not text.strip():
             return Result.err(CaptureError.EMPTY_RESPONSE)
+        text = redact_values(text, redactions)
         return Result.ok(CapturedOutput(raw_text=text, artifact_path=state_dir / artifact))
 
     def write(self) -> Result[None, CaptureError]:

agentic_dev_loop-1.0.0a9/src/agentic_dev_loop/engine/secrets.py

@@ -0,0 +1,118 @@
+"""Host-side secret store (unit 019): provider registry, run-start resolution,
+the ``.env*`` ban, and output scrubbing.
+
+Secrets are declared in the pipeline yaml as refs only — never values. At run
+start the engine resolves every declared ref host-side (``env`` provider
+first) and injects each value into a declaring step's exec env only. The
+``.env*`` ban keeps secret-bearing files out of the workspace, and the
+scrubber keeps resolved values out of every engine-written output path.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Protocol
+
+from agentic_dev_loop.core.config import PipelineConfig, StepConfig
+
+REDACTED = "[REDACTED]"
+ENV_FILE_WHITELIST = frozenset({".env.example", ".env.template", ".env.sample"})
+
+
+class SecretResolutionError(RuntimeError):
+    """A loud fail-fast secret failure naming the ref, step(s), and provider."""
+
+
+class SecretProvider(Protocol):
+    """A provider resolves locator keys to values, host-side, once per run."""
+
+    name: str
+
+    def resolve(self, keys: list[str]) -> dict[str, str]:
+        """Resolve each locator key; a missing key raises loudly."""
+        ...
+
+
+class EnvProvider:
+    """Resolve secrets from host environment variables (the shipped default).
+    ``key`` is both the host variable to read and the step env name to inject."""
+
+    name = "env"
+
+    def __init__(self, environ: Mapping[str, str] | None = None):
+        self._environ = os.environ if environ is None else environ
+
+    def resolve(self, keys: list[str]) -> dict[str, str]:
+        missing = sorted(k for k in keys if k not in self._environ)
+        if missing:
+            raise SecretResolutionError(
+                "environment variable(s) not set: " + ", ".join(missing))
+        return {k: self._environ[k] for k in keys}
+
+
+PROVIDERS: dict[str, SecretProvider] = {"env": EnvProvider()}
+
+
+def resolve_secrets(cfg: PipelineConfig,
+                    environ: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Resolve every declared ref host-side once (run start). Returns
+    ``{ref_name: value}``. An unresolvable ref or unknown provider fails fast,
+    naming the ref, the declaring step(s), and the provider error."""
+    if environ is not None:
+        providers = {"env": EnvProvider(environ)}
+    else:
+        providers = PROVIDERS
+    resolved: dict[str, str] = {}
+    for ref, spec in cfg.secrets.items():
+        provider = providers.get(spec.from_)
+        if provider is None:
+            raise SecretResolutionError(
+                f"secret ref {ref!r}: unknown provider {spec.from_!r}")
+        try:
+            resolved[ref] = provider.resolve([spec.key])[spec.key]
+        except SecretResolutionError as e:
+            steps = [s.name for s in cfg.steps if ref in s.secrets]
+            raise SecretResolutionError(
+                f"secret ref {ref!r} (provider {spec.from_!r}, key {spec.key!r})"
+                f" used by step(s) {steps or ['<none>']}: {e}") from e
+    return resolved
+
+
+def step_secret_env(cfg: PipelineConfig, step: StepConfig,
+                    resolved: Mapping[str, str]) -> dict[str, str]:
+    """The ``{env_name: value}`` mapping to inject for one step: only the refs
+    it declares, keyed by each ref's ``key`` (the env name the step reads)."""
+    return {cfg.secrets[ref].key: resolved[ref] for ref in step.secrets}
+
+
+def redact_values(text: str, values: Iterable[str]) -> str:
+    """Replace every resolved secret value in ``text`` with ``[REDACTED]``.
+    Longest-first so a value that is a substring of another is fully removed."""
+    if not text:
+        return text
+    secrets = sorted({v for v in values if v}, key=len, reverse=True)
+    for value in secrets:
+        text = text.replace(value, REDACTED)
+    return text
+
+
+def scan_env_files(workspace: Path | str) -> None:
+    """The ``.env*`` ban: any ``.env*`` file at the workspace root — other than
+    the convention fixtures (``.env.example`` / ``.env.template`` /
+    ``.env.sample``) — fails fast, naming the files and the remedy. Applies
+    regardless of ``network:`` flags: the workspace must simply not hold
+    secrets."""
+    root = Path(workspace)
+    hits = sorted(
+        p.name for p in root.glob(".env*")
+        if p.is_file() and p.name not in ENV_FILE_WHITELIST
+    )
+    if hits:
+        raise SecretResolutionError(
+            "secret-bearing file(s) found in the workspace root: "
+            + ", ".join(hits)
+            + " — move these values into `secrets:` refs / host env and "
+            "delete the files (`.env.example`, `.env.template`, `.env.sample` "
+            "are allowed fixtures)")

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/src/agentic_dev_loop/engine/stages.py

@@ -23,7 +23,7 @@ import os
 import subprocess
 import sys
 import traceback
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -34,6 +34,7 @@ from .agents import load_agent, register_sandbox_terminal
 from agentic_dev_loop.core.config import TERMINALS, PipelineConfig, Route, StepConfig, route_target
 from .isolation import SandboxExecutionRequest, command_argv, resolve_sandbox_env
 from .outputs import CapturedOutput
+from .secrets import redact_values, step_secret_env
 from agentic_dev_loop.core.verdict import Verdict
 from .proc import (child_env, host_shell_execution, kill_process_tree,
                    needs_shell, split_command)
@@ -60,6 +61,7 @@ class Runtime:
     state_dir: Path
     workspace: Path
     sandbox: Sandbox | None = None
+    secrets: dict[str, str] = field(default_factory=dict)
 
 
 def prompt_dir(runtime: Runtime) -> str:
@@ -112,7 +114,9 @@ def run_agent(agent_name: str, message: str, runtime: Runtime,
                 workspace=str(runtime.workspace),
                 pipeline=runtime.cfg.name,
                 step=step.name if step is not None else None,
-                network=step.network if step is not None else False)
+                network=step.network if step is not None else False,
+                secrets=(step_secret_env(runtime.cfg, step, runtime.secrets)
+                         if step is not None else None))
         agent = load_agent(runtime.agents_dir, agent_name, runtime.llm)
         conv = Conversation(agent=agent, workspace=str(runtime.workspace),
                             max_iteration_per_run=max_iterations)
@@ -123,7 +127,9 @@ def run_agent(agent_name: str, message: str, runtime: Runtime,
 
         if step is not None and (step.artifact is not None or step.produces):
             artifact = step.artifact if step.artifact is not None else step.produces[0]
-            captured = CapturedOutput.from_agent_result(conv, artifact, runtime.state_dir)
+            captured = CapturedOutput.from_agent_result(
+                conv, artifact, runtime.state_dir,
+                redactions=tuple(runtime.secrets.values()))
             if captured.is_err():
                 return AgentResult(ok=True, truncated=truncated,
                                    capture_error=captured.error.value)
@@ -135,7 +141,7 @@ def run_agent(agent_name: str, message: str, runtime: Runtime,
                                response=captured.unwrap().raw_text)
         return AgentResult(ok=True, truncated=truncated)
     except Exception:
-        err = traceback.format_exc()
+        err = redact_values(traceback.format_exc(), runtime.secrets.values())
         print(err[-4000:], file=sys.stderr, flush=True)
         runtime.state_dir.mkdir(parents=True, exist_ok=True)
         error_path = runtime.state_dir / LAST_ERROR
@@ -338,7 +344,8 @@ def make_command_node(runtime: Runtime, step: StepConfig):
     timeout = step.timeout if step.timeout is not None else DEFAULT_COMMAND_TIMEOUT
     sandbox = runtime.sandbox
     if sandbox is not None:
-        env = resolve_sandbox_env(step.env)
+        env = resolve_sandbox_env(
+            step.env, secrets=step_secret_env(runtime.cfg, step, runtime.secrets))
     else:
         env = child_env(runtime.cfg.env_allowlist, runtime.cfg.llm.api_key_env)
 
@@ -352,9 +359,12 @@ def make_command_node(runtime: Runtime, step: StepConfig):
                 sandbox=sandbox, pipeline=runtime.cfg.name, step=step.name,
                 network=step.network)
         except Exception:
-            print(traceback.format_exc()[-4000:], file=sys.stderr, flush=True)
+            print(redact_values(traceback.format_exc(),
+                                runtime.secrets.values())[-4000:],
+                  file=sys.stderr, flush=True)
             return {"failed": True, "failed_step": step.name}
         if output:
+            output = redact_values(output, runtime.secrets.values())
             print(output, end="" if output.endswith("\n") else "\n", flush=True)
         merged = {**state["step_verdicts"],
                   step.name: "pass" if exit_code == 0 else "fail"}
@@ -383,7 +393,9 @@ def make_action_node(runtime: Runtime, step: StepConfig):
         try:
             return fn(state, step.params) or {}
         except Exception:
-            print(traceback.format_exc()[-4000:], file=sys.stderr, flush=True)
+            print(redact_values(traceback.format_exc(),
+                                runtime.secrets.values())[-4000:],
+                  file=sys.stderr, flush=True)
             return {"failed": True, "failed_step": step.name}
 
     return node

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a9}/src/agentic_dev_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a8
+Version: 1.0.0a9
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -192,9 +192,49 @@ steps:
 | `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
 | `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:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
+| `secrets:` (top-level) / step `secrets:` | Declares secret **refs only — never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
 | `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
 
+### Secrets (`secrets:`) — refs only, never values
+
+Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.
+Declare the refs at the top level and opt each step into the refs it needs:
+
+```yaml
+secrets:                              # refs only — never values
+  kinde-client-secret:                # ref name (arbitrary)
+    from: env                         # provider name
+    key: KINDIE_CLIENT_SECRET         # provider-specific locator
+  r2-keys:
+    from: env
+    key: YOSK_R2_KEYS
+
+steps:
+  - name: qa
+    agent: qa
+    secrets: [kinde-client-secret, r2-keys]
+```
+
+- The engine resolves every declared ref **host-side at run start** (the `env`
+  provider reads the named host environment variable). A missing variable, an
+  unknown provider, or a ref a step lists without declaring it fails fast —
+  naming the ref, the step, and the provider error. No silent fallback.
+- A resolved secret is injected into a step's exec env **only when that step
+  lists the ref** — the same path step `env:` uses, no new channel. The secret
+  never reaches the provision container, `state_dir`, or any other step.
+- Prefer a mechanical `command` step for secret-consuming work (a script runs
+  the app with creds) so the LLM and the secret never meet; an `agent` step
+  holds a secret only when its job genuinely requires it.
+- **`.env*` ban.** At run start the workspace root is scanned for `.env*`
+  files. Any hit fails fast, naming the files, with the remedy text. The
+  convention fixtures `.env.example`, `.env.template`, and `.env.sample` are
+  whitelisted. This applies regardless of `network:` flags.
+- **Output scrubbing.** Resolved secret values are scrubbed from every
+  engine-written output — captured step output, retry notes, artifacts, and
+  `state_dir` files. (Hygiene: the declaring step's agent has already seen
+  the value in its own env.)
+
 ### Per-stage networking
 
 The sandbox is network-off by default. A step that legitimately needs egress —
@@ -226,8 +266,7 @@ steps:
 git clone git@github.com:lukedawilson/agentic-dev-loop.git
 cd agentic-dev-loop
 ./setup-venv.sh                       # idempotent .venv setup (never touches bare pip)
-# create .env with your LLM key (loaded by trigger-agentic-dev-loop.sh, never committed):
-#   echo 'OPENAI_API_KEY=...' > .env
+export OPENAI_API_KEY=...           # set your LLM key in the host env (no .env in the repo)
 python -m pytest tests/ -q            # fast suite
 python -m pytest tests/ -q -m "not docker"   # skip engine-dependent tests
 ./trigger-agentic-dev-loop.sh --dry-run      # run the shipped pipeline against this repo