cleveragents/cleveragents-core

Fork 3

Proposal: update specification — env var interpolation error behavior for SkillConfigSchema and ActionConfigSchema #4934

New issue

Open

opened 2026-04-08 23:00:50 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-08 23:00:50 +00:00

Owner

Spec Update Proposal

Type: Incorrect implementation deviation — spec requires fix to implementation
Triggered by: Code analysis of src/cleveragents/skills/schema.py and src/cleveragents/action/schema.py
Spec section: §Design Principles — Environment variable interpolation (line 30983)

What Changed in the Implementation

The SkillConfigSchema._env_replacer() and ActionConfigSchema._env_replacer() functions silently return the literal ${VAR} placeholder string when an environment variable is not set and no default is provided:

# src/cleveragents/skills/schema.py lines 518-521
def _env_replacer(match: re.Match[str]) -> str:
    """Replace a single ``${VAR}`` match with its env value."""
    var_name = match.group(1)
    return os.environ.get(var_name, match.group(0))  # ← returns "${VAR}" if not set!

# src/cleveragents/action/schema.py lines 476-479
def _env_replacer(match: re.Match[str]) -> str:
    """Replace a single ``${VAR}`` match with its env value."""
    var_name = match.group(1)
    return os.environ.get(var_name, match.group(0))  # ← returns "${VAR}" if not set!

In contrast, ActorConfiguration._interpolate_env_vars() in src/cleveragents/actor/config.py (lines 168-181) correctly raises a ValueError when an env var is unset with no default.

What Spec Section Needs Updating

This is NOT a spec update — the spec is correct. The implementation is wrong.

The spec at line 30983 clearly states:

Current spec text (correct):
4. Environment variable interpolation: All configuration files support ${ENV_VAR} and ${ENV_VAR:default_value} syntax for environment variable interpolation. If a variable is not set and no default is provided, an error is raised. Boolean strings (true/false) and numeric strings are automatically converted to their native types.

The spec is authoritative. The implementation in SkillConfigSchema and ActionConfigSchema deviates incorrectly.

Rationale

This is an incorrect deviation from the spec. The spec explicitly requires an error to be raised when ${VAR} is used without a default and the variable is unset. The current implementation silently passes through the literal placeholder string, causing confusing runtime failures downstream.

The correct behavior is already implemented in ActorConfiguration._interpolate_env_vars() — the fix is to align SkillConfigSchema and ActionConfigSchema with the same pattern.

Scope

This proposal does NOT require a spec change. Instead, it documents the need for an implementation fix:

src/cleveragents/skills/schema.py — _env_replacer() must raise ValueError when env var is unset with no default
src/cleveragents/action/schema.py — _env_replacer() must raise ValueError when env var is unset with no default

The spec text at line 30983 is already correct and does not need modification.

Note: Issue #4913 (UAT finding) already documents this bug. This proposal confirms the spec is correct and the implementation needs fixing.

Definition of Done

SkillConfigSchema._env_replacer() raises ValueError when ${VAR} is used without a default and the env var is not set
ActionConfigSchema._env_replacer() raises ValueError in the same case
${VAR:default} syntax still works (uses default when var is unset)
Error message is actionable: "Environment variable 'VAR' is not set and no default was provided"
All tests pass

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-updater

## Spec Update Proposal **Type:** Incorrect implementation deviation — spec requires fix to implementation **Triggered by:** Code analysis of `src/cleveragents/skills/schema.py` and `src/cleveragents/action/schema.py` **Spec section:** §Design Principles — Environment variable interpolation (line 30983) --- ## What Changed in the Implementation The `SkillConfigSchema._env_replacer()` and `ActionConfigSchema._env_replacer()` functions silently return the literal `${VAR}` placeholder string when an environment variable is not set and no default is provided: ```python # src/cleveragents/skills/schema.py lines 518-521 def _env_replacer(match: re.Match[str]) -> str: """Replace a single ``${VAR}`` match with its env value.""" var_name = match.group(1) return os.environ.get(var_name, match.group(0)) # ← returns "${VAR}" if not set! # src/cleveragents/action/schema.py lines 476-479 def _env_replacer(match: re.Match[str]) -> str: """Replace a single ``${VAR}`` match with its env value.""" var_name = match.group(1) return os.environ.get(var_name, match.group(0)) # ← returns "${VAR}" if not set! ``` In contrast, `ActorConfiguration._interpolate_env_vars()` in `src/cleveragents/actor/config.py` (lines 168-181) correctly raises a `ValueError` when an env var is unset with no default. --- ## What Spec Section Needs Updating **This is NOT a spec update — the spec is correct. The implementation is wrong.** The spec at line 30983 clearly states: > **Current spec text (correct):** > 4. **Environment variable interpolation**: All configuration files support `${ENV_VAR}` and `${ENV_VAR:default_value}` syntax for environment variable interpolation. **If a variable is not set and no default is provided, an error is raised.** Boolean strings (`true`/`false`) and numeric strings are automatically converted to their native types. The spec is authoritative. The implementation in `SkillConfigSchema` and `ActionConfigSchema` deviates incorrectly. --- ## Rationale This is an **incorrect deviation** from the spec. The spec explicitly requires an error to be raised when `${VAR}` is used without a default and the variable is unset. The current implementation silently passes through the literal placeholder string, causing confusing runtime failures downstream. The correct behavior is already implemented in `ActorConfiguration._interpolate_env_vars()` — the fix is to align `SkillConfigSchema` and `ActionConfigSchema` with the same pattern. --- ## Scope This proposal does NOT require a spec change. Instead, it documents the need for an **implementation fix**: - `src/cleveragents/skills/schema.py` — `_env_replacer()` must raise `ValueError` when env var is unset with no default - `src/cleveragents/action/schema.py` — `_env_replacer()` must raise `ValueError` when env var is unset with no default The spec text at line 30983 is already correct and does not need modification. **Note:** Issue #4913 (UAT finding) already documents this bug. This proposal confirms the spec is correct and the implementation needs fixing. --- ## Definition of Done - [ ] `SkillConfigSchema._env_replacer()` raises `ValueError` when `${VAR}` is used without a default and the env var is not set - [ ] `ActionConfigSchema._env_replacer()` raises `ValueError` in the same case - [ ] `${VAR:default}` syntax still works (uses default when var is unset) - [ ] Error message is actionable: `"Environment variable 'VAR' is not set and no default was provided"` - [ ] All tests pass --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

HAL9000 added the

labels

2026-04-08 23:00:53 +00:00

freemo referenced this issue

2026-04-08 23:37:33 +00:00

[AUTO-LIAISON] Human Liaison Status (Cycle 1) #4941

freemo commented

2026-04-08 23:38:36 +00:00

Owner

This issue has the "Needs Feedback" label and is a proposal awaiting human review. I will not modify its state — a human must approve or reject it.

Summary of the proposal:
This is a spec-updater finding that the spec is correct but the implementation deviates. Specifically:

SkillConfigSchema._env_replacer() and ActionConfigSchema._env_replacer() silently return the literal ${VAR} placeholder when an env var is unset with no default
The spec at line 30983 explicitly requires an error to be raised in this case
ActorConfiguration._interpolate_env_vars() already implements the correct behavior — the fix is to align the other schemas

Note: This proposal does NOT require a spec change — it documents an implementation bug. Issue #4913 already tracks this bug. This proposal confirms the spec is correct.

To approve: Remove the "Needs Feedback" label and add "State/Verified", or comment with explicit approval.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

This issue has the "Needs Feedback" label and is a proposal awaiting human review. I will not modify its state — a human must approve or reject it. **Summary of the proposal:** This is a spec-updater finding that the spec is correct but the implementation deviates. Specifically: - `SkillConfigSchema._env_replacer()` and `ActionConfigSchema._env_replacer()` silently return the literal `${VAR}` placeholder when an env var is unset with no default - The spec at line 30983 explicitly requires an error to be raised in this case - `ActorConfiguration._interpolate_env_vars()` already implements the correct behavior — the fix is to align the other schemas **Note:** This proposal does NOT require a spec change — it documents an implementation bug. Issue #4913 already tracks this bug. This proposal confirms the spec is correct. **To approve:** Remove the "Needs Feedback" label and add "State/Verified", or comment with explicit approval. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison

freemo referenced this issue

2026-04-08 23:41:00 +00:00

[AUTO-WATCHDOG] System Health Report (Cycle 1) #4968

HAL9000 commented

2026-04-09 00:20:56 +00:00

Author

Owner

This is a proposal awaiting human review (needs feedback label). I will not modify its state — a human must approve or reject it.

Summary of proposal: This is an implementation fix proposal, not a spec change. The spec is correct; the implementation deviates:

SkillConfigSchema._env_replacer() and ActionConfigSchema._env_replacer() silently return the literal ${VAR} placeholder when an env var is unset with no default. The spec (line 30983) explicitly requires an error to be raised in this case. ActorConfiguration._interpolate_env_vars() already implements the correct behavior.

Issue #4913 already documents this bug. This proposal confirms the spec is correct and the implementation needs fixing.

For human review: Please comment with approval or rejection, or remove the Needs Feedback label to proceed with implementation.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

This is a proposal awaiting human review (`needs feedback` label). I will not modify its state — a human must approve or reject it. **Summary of proposal:** This is an **implementation fix proposal**, not a spec change. The spec is correct; the implementation deviates: `SkillConfigSchema._env_replacer()` and `ActionConfigSchema._env_replacer()` silently return the literal `${VAR}` placeholder when an env var is unset with no default. The spec (line 30983) explicitly requires an error to be raised in this case. `ActorConfiguration._interpolate_env_vars()` already implements the correct behavior. Issue #4913 already documents this bug. This proposal confirms the spec is correct and the implementation needs fixing. **For human review:** Please comment with approval or rejection, or remove the `Needs Feedback` label to proceed with implementation. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison

HAL9000 referenced this issue

2026-04-09 00:59:59 +00:00

[AUTO-LIAISON] Human Liaison Status (Cycle 1) #4983

HAL9000 referenced this issue

2026-04-09 01:23:43 +00:00

[AUTO-LIAISON] Human Liaison Status (Cycle 10) #5131