fix(cli): load the agent's .env into locally run ACP and worker processes

[michaelxu2288]

Problem

getting_started/project_structure.md says a .env next to manifest.yaml "is automatically loaded when placed alongside your manifest.yaml file, but only for local development". Nothing does that today:

• agentex agents run builds the child environment from os.environ plus the manifest (create_agent_environment).
• EnvironmentVariables.refresh() loads .env from Path(__file__).parents[2], which is site-packages for an installed SDK, never the agent folder, and .env.local from cwd.parent.
• ProjectConfigLoader._load_env only feeds config templating.

Values from .env reach a process only when some import happens to call load_dotenv() first. litellm does, on import (litellm/__init__.py), which is why the Temporal + OpenAI Agents template appears to work (its model client is built lazily inside the activity, after imports) while Temporal + Pydantic AI fails at import time of project/agent.py with openai.OpenAIError: Missing credentials. Verified with a print at the top of both workers: OpenAI Agents worker sees LITELLM_API_KEY only after its imports; the Pydantic AI worker never does.

Fix

create_agent_environment(manifest, manifest_dir) merges <manifest dir>/.env (python-dotenv dotenv_values, already a dependency) into the environment handed to both the ACP and worker subprocesses, without overriding variables already set in the shell (python-dotenv semantics). run_agent passes manifest_file.parent. 16-line diff plus three tests (merge, shell precedence, no file / no manifest_dir) that render a real manifest via the init helpers.

Verification

• tests/lib/cli/test_run_handlers_env.py: 3 passed; streaming handler tests still pass; ruff clean.
• Live, Temporal + Pydantic AI scaffold with only LITELLM_API_KEY in .env, patched SDK installed into its venv: before, no reply and Missing credentials; after, reply in 4.7 s, zero worker errors.

Pairs with #514 ("fix(templates): map LITELLM_API_KEY to OPENAI_API_KEY in Temporal workers"): once .env is in the process environment from the start, that mapping at the top of run_worker.py becomes deterministic instead of depending on import order.

Confidence Score: 3/5

The PR is not ready to merge while .env can replace manifest-derived settings and deployed agents are missing from metadata-filtered lists.

Findings

1.  Dotenv overrides manifest settings ▶

Fix with agent prompt

### Issue 1
src/agentex/lib/cli/handlers/run_handlers.py:476-478
A `.env` entry can now overwrite manifest-derived runtime settings such as `AGENT_NAME`, `ACP_PORT`, `WORKFLOW_TASK_QUEUE`, and `HEALTH_CHECK_PORT`. These values are added through `env_vars`, but `manifest_env` contains only the explicit `agent.env` mapping. A conflicting dotenv value therefore replaces the manifest-derived value and can start the ACP or worker with the wrong identity, port, task queue, or health-check configuration. Preserve all manifest-derived keys while still allowing `.env` to replace built-in local defaults.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Local agent runs now load .env from beside manifest.yaml into both child processes, and ACP task creation waits for its handler before replying. The PR also changes the production API URL and updates release, contributor, and security-scan workflows.

• Keeps local process settings consistent while respecting shell and manifest overrides.
• Makes a created task available before callers send events.
• Moves release and repository automation to the main-based workflow.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  M[manifest.yaml] --> E[Local environment]
  D[.env] --> E
  S[Shell variables] --> E
  E --> A[ACP process]
  E --> W[Worker process]

Loading

_{Reviews (3) · Last reviewed commit: "fix(cli): apply .env after the built-in ..."}

[greptile-apps]

Dotenv overrides manifest settings

A .env entry can now overwrite manifest-derived runtime settings such as AGENT_NAME, ACP_PORT, WORKFLOW_TASK_QUEUE, and HEALTH_CHECK_PORT. These values are added through env_vars, but manifest_env contains only the explicit agent.env mapping. A conflicting dotenv value therefore replaces the manifest-derived value and can start the ACP or worker with the wrong identity, port, task queue, or health-check configuration. Preserve all manifest-derived keys while still allowing .env to replace built-in local defaults.

Knowledge Base Used: Command-line workflows

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/cli/handlers/run_handlers.py
Line: 476-478

Comment:
**Dotenv overrides manifest settings**

A `.env` entry can now overwrite manifest-derived runtime settings such as `AGENT_NAME`, `ACP_PORT`, `WORKFLOW_TASK_QUEUE`, and `HEALTH_CHECK_PORT`. These values are added through `env_vars`, but `manifest_env` contains only the explicit `agent.env` mapping. A conflicting dotenv value therefore replaces the manifest-derived value and can start the ACP or worker with the wrong identity, port, task queue, or health-check configuration. Preserve all manifest-derived keys while still allowing `.env` to replace built-in local defaults.

**Knowledge Base Used:** [Command-line workflows](https://app.greptile.com/scale-ai/-/custom-context/knowledge-base/scaleapi/scale-agentex-python/-/docs/command-line-workflows.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.