poe-code/agent: support per-run environment overrides for composable AgentBuilder runs

[kamilio]

Summary

The released public SpawnOptions.env fixes per-invocation environment overrides for spawn(...) / spawn.pretty(...), but the composable public poe-code/agent runtime does not expose an equivalent per-run environment option.

AgentRunOptions currently supports signal, resume, skills, iteration limits, provider configuration, cwd, system prompt, ACP model, stdout, and log path, but no env field. AgentBuilder.run(...), .stream(...), and .acp(...) therefore cannot receive isolated per-run environment overrides.

Consumer impact

quora/bug-analyzer uses the composable runtime for an isolated mention agent:

await agent()
  .model(model)
  .use(...)
  .mcp(...)
  .run(prompt)

The agent and its plugins need a run-specific environment. Because the runtime has no public per-run env input, the consumer must still temporarily mutate global process.env and serialize these runs, even after adopting poe-code@3.0.254 and removing that workaround from normal spawn.pretty(...) calls.

MCP server configs can receive their own env, but that does not provide the environment to the agent runtime/plugins themselves.

Requested capability

Add a documented per-run environment override to the composable runtime, for example:

await agent().run(prompt, {
  env: {
    PATH: workspacePath,
    AUTOMATIONS_DRY_RUN: "1",
  },
})

The same option should be available consistently on run, stream, and acp where applicable, without mutating the parent process environment.

Acceptance criteria

• Public AgentRunOptions accepts per-run environment overrides.
• AgentBuilder.run, .stream, and .acp propagate the isolated environment consistently.
• Providers, plugins, and MCP servers observe the intended resulting environment according to documented precedence.
• Parallel runs with conflicting values remain isolated.
• The parent process environment is never mutated.
• Tests cover parallel conflicting environments and inheritance/override behavior.

[kamilio]

Resolved on main with composable AgentRunOptions.env support wired through normal, interactive, ACP, and SDK spawn paths. Parallel/per-run behavior is covered by tests. Released in poe-code@3.0.256 via successful workflow run 27441292197. Closing as released.