AGEN-5 - trckr

← AGEN-5

feature

Created: 2026-02-03 • Updated: 2026-02-03

Relationships Loading...

# Environment Variable Interpolation in Templates

Add {{env.VAR_NAME}} syntax to access environment variables in template variables and prompts.

## Scope
~150 lines of code + tests

## Implementation
1. Add \`env\` to reserved variables namespace (variables.py)
2. In \`ReservedVariables.get_reserved_vars()\`, add:
   \`\`\`python
   reserved_vars["env"] = os.environ.copy()
   \`\`\`
3. After workflow/task env merging (from Ticket AGEN-3), update env dict
4. Support in prompts: \`{{env.HOME}}\`, \`{{env.MY_VAR}}\`
5. Support in template variables: \`my-path: "{{env.DATA_DIR}}/file"\`

## YAML API
\`\`\`yaml
environment:
  MY_VAR: "custom_value"

template-variables:
  data-path: "{{env.HOME}}/data"

task:
  - show-env:
      prompt: |
        User home: {{env.HOME}}
        Custom var: {{env.MY_VAR}}
        Data path: {{data-path}}
\`\`\`

## Files to Modify
- src/variables.py (~60 lines)
- src/utils.py (~30 lines)
- tests/test_env_interpolation.py (new, ~60 lines)

## Tests Required
- Access system env vars via {{env.PATH}}
- Access workflow env vars via {{env.MY_VAR}}
- Access task env vars via {{env.TASK_VAR}}
- Use env var in template variable definition
- Env vars with dots/hyphens/underscores in names
- Undefined env var behavior (empty string or error)

## Dependencies
**Blocks:** None
**Blocked by:** AGEN-3 (Task-level environment variables)

Requires task-level env to be implemented first so workflow/task env merging exists.

## QA Validation Steps

### 1. System Env Test
**Action:**
\`\`\`yaml
task:
  - check-home:
      prompt: "Create output.txt with: HOME={{env.HOME}}"
\`\`\`
**Expected:** {{env.HOME}} resolves to actual home directory
**Verify:** output.txt contains /Users/username or equivalent

### 2. Workflow Env Test
**Action:**
\`\`\`yaml
environment:
  MY_CUSTOM_VAR: "test_value"
task:
  - check:
      prompt: "Create output.txt with: VAR={{env.MY_CUSTOM_VAR}}"
\`\`\`
**Expected:** {{env.MY_CUSTOM_VAR}} resolves to test_value
**Verify:** output.txt shows correct value

### 3. Task Env Override Test
**Action:**
\`\`\`yaml
environment:
  VAR: "workflow"
task:
  - override:
      env:
        VAR: "task"
      prompt: "Create output.txt with: VAR={{env.VAR}}"
\`\`\`
**Expected:** {{env.VAR}} shows task value (override)
**Verify:** output.txt contains "task" not "workflow"

### 4. Template Variable Integration Test
**Action:**
\`\`\`yaml
environment:
  DATA_DIR: "/tmp/data"
template-variables:
  config-file: "{{env.DATA_DIR}}/config.json"
task:
  - use:
      prompt: "Read {{config-file}}"
\`\`\`
**Expected:** config-file resolves to /tmp/data/config.json
**Verify:** Prompt contains full interpolated path

### Pass Criteria
✅ All 4 tests pass
✅ Works with workflow env, task env, system env
✅ Unit tests pass

### Fail Criteria
❌ Any test fails
❌ System env vars not accessible
❌ Task env override doesn't work

Pull Requests (comma-separated URLs)

Attachments

Comments (3)

QA Agent · 2026-02-03

## QA Verification Complete **Status:** VERIFIED - Implementation works as claimed **Testing Summary:** - All 28 env interpolation unit tests pass - Full test suite: 790 passed, 18 skipped (no failures) - All 4 QA validation scenarios verified and passing - Test coverage: 99% on variables.py, 78% overall - Dry-run mode confirms correct behavior - Example workflow demonstrates all features **Verified Functionality:** 1. System env vars accessible via {{env.HOME}}, {{env.PATH}} 2. Workflow env vars accessible via {{env.MY_CUSTOM_VAR}} 3. Task env override works correctly: task > workflow > system 4. Env vars in template variables work correctly 5. Undefined env vars return empty string (graceful handling) 6. Non-string values converted to strings 7. Edge cases handled properly (None, special chars, empty dicts) **Code Quality:** - Clean implementation following project patterns - Proper integration with AGEN-3 (task-level env) - No security vulnerabilities - No performance degradation - No breaking changes - Comprehensive documentation **Evidence:** - Full QA report: /tmp/qa-AGEN-5.md - Test artifacts and commands documented - All acceptance criteria met **Recommendation:** Production-ready, no issues found. Verified by: QA Agent Date: 2026-02-03

agent · 2026-02-03

## Implementation Complete **What was implemented:** Added `{{env.VAR_NAME}}` syntax to access environment variables in template variables and prompts. **Changes made:** 1. **src/variables.py** (~20 lines) - Added 'env' to `RESERVED_NAMES` constant - Modified `get_reserved_vars()` to accept `workflow_env` and `task_env` parameters - Build merged environment dict with precedence: system < workflow < task 2. **src/cli.py** (~3 lines) - Pass workflow `environment:` block to `get_reserved_vars()` 3. **src/executor.py** (~12 lines) - Inject task-level `env:` into `resolved_vars` before prompt interpolation - Creates copy of resolved_vars to avoid modifying original 4. **tests/test_env_interpolation.py** (new, 348 lines) - 28 comprehensive tests covering all use cases - Tests for system, workflow, and task env access - Precedence tests, edge cases, and template variable integration 5. **Documentation updates:** - CLAUDE.md: Added env interpolation section - examples/38-env-interpolation.yaml: Working example **How it was verified:** - All 774 tests pass (including 28 new tests) - Manual verification with dry-run mode - Coverage: 78% overall, 99% on variables.py **Commit:** 6811b1e - AGEN-5: Implement environment variable interpolation in templates

triage-agent · 2026-02-03

## Feature Triage Complete **Status:** NOT IMPLEMENTED - Ready for implementation **Summary:** This feature adds `{{env.VAR_NAME}}` syntax to access environment variables in template variables and prompts. The feature builds on AGEN-3 (task-level env vars) which is complete. **Implementation Location:** - `src/variables.py` - Add `env` to reserved vars namespace (~30 lines) - `src/utils.py` - Handle env var interpolation (~20 lines) - `src/executor.py` - Pass merged env to interpolation (~10 lines) - `tests/test_env_interpolation.py` - New test file (~60 lines) **Complexity:** Low-Medium **Estimated Scope:** ~130-150 lines as stated in issue **Key Implementation Notes:** 1. Add `env` to `RESERVED_NAMES` to prevent user override 2. Modify `get_reserved_vars()` to accept workflow_env/task_env params 3. Leverage existing dot notation support in `_simple_interpolate()` 4. Handle undefined env vars as empty string (consistent with current behavior) 5. Env vars with dots in names NOT supported (dots are namespace separators) **Architecture Consideration:** - Template-variables are resolved before task execution, so only workflow env (not task env) will be available in template-variable definitions - Task env will be available in prompt interpolation **Dependency:** AGEN-3 (Task-level environment variables) - **COMPLETED** ✅ See full triage report at: /tmp/triage-AGEN-5.md