Coding Agent Loop Spec Compliance (AttractorEx)

Copy Markdown View Source

This file maps AttractorEx.Agent.* behavior to the upstream coding-agent-loop specification.

The durable HTTP runtime introduced for the runtime-foundation workstream is shared execution infrastructure around this layer. It does not change agent-loop session semantics directly, but it does provide restart-safe persistence for outer runtime surfaces that host those sessions.

Source Documents

Scope

Implementation:

  1. lib/attractor_ex/agent/session.ex
  2. lib/attractor_ex/agent/session_config.ex
  3. lib/attractor_ex/agent/provider_profile.ex
  4. lib/attractor_ex/agent/builtin_tools.ex
  5. lib/attractor_ex/agent/apply_patch.ex
  6. lib/attractor_ex/agent/tool.ex
  7. lib/attractor_ex/agent/tool_registry.ex
  8. lib/attractor_ex/agent/execution_environment.ex
  9. lib/attractor_ex/agent/local_execution_environment.ex

Tests:

  1. test/attractor_ex/agent/session_test.exs
  2. test/attractor_ex/agent/primitives_test.exs
  3. test/attractor_ex/agent/builtin_tools_test.exs

Section-by-Section Status

Legend: implemented, partial, not implemented.

Upstream sectionStatusNotes
2. Agentic LoopimplementedSession lifecycle, loop rounds, natural completion, limits, steering/follow-up, loop detection, spec-style session event emission, full-output tool-call host events, and model-recoverable tool validation failures are covered.
3. Provider-Aligned ToolsetsimplementedOpenAI/Anthropic/Gemini presets now expose provider-specific tool bundles and capability flags, including OpenAI apply_patch, Anthropic/Gemini edit_file, Gemini read_many_files/list_dir, provider-native shell naming, and opt-in Gemini web_search/web_fetch support via ProviderProfile.gemini(web_tools: true). Byte-for-byte upstream harness/prompt parity is still not claimed.
4. Tool Execution EnvironmentimplementedExecutionEnvironment now covers working directory, platform, file reads/writes, directory listing, globbing, grep, shell execution, and environment context, with LocalExecutionEnvironment implementing the contract.
5. Tool Output and Context ManagementimplementedCharacter-first then line truncation, per-tool limits, timeout controls, and bounded event payload behavior are implemented/tested.
6. System Prompts and Environment ContextimplementedLayered prompt construction now includes provider-specific base guidance, provider/model metadata, platform, tool inventory, serialized environment context, and ancestor-discovered instruction docs (AGENTS.md, provider files, .codex/instructions.md) with root-to-leaf ordering, a shared 32 KB budget, and custom builder hooks preserved.
7. SubagentsimplementedSession-managed spawn_agent, send_input, wait, and close_agent tools now create child sessions with independent history, shared execution environment, model/turn overrides, and enforced max_subagent_depth.
8. Out of Scopen/aInformational section.
9. Definition of DoneimplementedThe session loop, provider presets, registry dispatch/error paths, truncation policy, steering/follow-up controls, reasoning controls, layered prompt context, local execution environment contract, subagent lifecycle, and maintained event surface are implemented and covered by tests. Exact provider-native prompt/tool-harness parity is still tracked separately as a known non-blocking gap.
Appendix A (apply_patch v4a)partialA built-in apply_patch tool now parses and applies add/delete/update/move operations in the appendix-style envelope for local sessions. Full appendix-edge-case coverage and exhaustive parity validation remain open.
Appendix B (error handling)implementedTool/session error propagation and recovery behaviors are implemented, and the underlying Unified LLM layer now contributes typed provider errors plus client-side retry/backoff semantics for recoverable LLM failures.

Verified Behaviors (with tests)

  1. Session lifecycle and closure/abort behavior.
  2. Tool call normalization and robust argument parsing.
  3. Unknown tool error results (model-recoverable).
  4. Steering and follow-up sequencing.
  5. Loop detection and turn/tool-round limits.
  6. Parallel tool call execution when enabled by profile.
  7. Timeout handling including late message drainage.
  8. Character+line truncation behavior and bounded event output.
  9. Tool failure capture (raise/throw/exit) and LLM error shutdown.
  10. Spec-aligned session event surface including assistant_text_start, assistant_text_delta, tool_call_output_delta, error, and full untruncated tool_call_end payloads for host integrations.
  11. Reasoning effort default/override and working-dir fallback logic.
  12. Provider presets with provider-specific coding-agent tool bundles, capability flags, and a maintained OpenAI/Anthropic/Gemini integration matrix.
  13. Execution-environment file/glob/grep/shell primitives.
  14. Tool-argument schema validation and session/context warning events.
  15. Root-to-leaf ancestor-based project instruction discovery for prompt context with a shared 32 KB truncation budget.
  16. Subagent lifecycle including spawn/input/wait/close flows, depth enforcement, and recoverable missing-agent errors.
  17. OpenAI-style apply_patch execution for local sessions plus Anthropic/Gemini-native edit/read-many/list-dir tool variants and opt-in Gemini web_search/web_fetch.
  18. Deterministic custom-tool registration on top of provider presets, including name-collision override behavior.
  19. Provider-specific base system-prompt guidance and the full typed session event inventory exposed via Event.supported_kinds/0.

Known Gaps vs Spec

  1. Provider-packaged toolsets and prompt bodies are aligned to codex-rs, Claude Code, and gemini-cli behaviors, but are not yet byte-for-byte harness copies.
  2. Built-in Gemini web tools are opt-in rather than enabled in the default preset to preserve a conservative local/network posture.
  3. apply_patch coverage is intentionally conservative and not yet validated against every appendix edge case.

Verification Commands

mix test test/attractor_ex/agent/primitives_test.exs test/attractor_ex/agent/session_test.exs
mix docs
mix precommit