kshitijk4poor
4d0cec9a7d
Second site of the same bug class #104444 fixes in apply_pending_steer_to_tool_results: _inject_steer_into_newest_tool_result (the drain that runs when a /steer lands during an API call) mutated the newest role:tool row in place. That row was already flushed append-only, so the replayed history diverged from the live request bytes at the injection point and broke the prompt cache exactly like the post-batch path. Deliver it the same way: a standalone user row inserted right after the newest tool result (not yet persisted, so the next flush writes it to the transcript). Restash when there is no tool row yet, unchanged. Stale comments claiming steer lands "in the newest tool result" and agent/AGENTS.md's alternation rule now describe the real shape.
113 lines
7.1 KiB
Markdown
113 lines
7.1 KiB
Markdown
# agent/ — AIAgent, turn loop, prompt, compression
|
|
|
|
Applies on top of the root `AGENTS.md` (prompt-caching invariant, facade + siblings rules).
|
|
|
|
## Shape
|
|
|
|
`run_agent.py` is the public facade: `AIAgent` is assembled from mixins (`agent/turn_facade.py`,
|
|
`client_lifecycle.py`, `stream_delivery.py`, `session_persistence.py`, `compression_facade.py`, ...).
|
|
Construction runs `agent/agent_init.py::init_agent`; a turn is
|
|
`agent/conversation_loop.py::run_conversation`, which `AIAgent.run_conversation` forwards to after
|
|
taking the session turn lease (`turn_facade_lease.py`). `AIAgent.__init__` takes ~60 parameters
|
|
(credentials, routing, callbacks, session context, budget, credential pool, ...) — read
|
|
`run_agent.py` for the list; the subset you usually touch: `base_url`, `api_key`, `provider`,
|
|
`api_mode` (`"chat_completions" | "codex_responses" | ...`), `model` (empty → resolved from
|
|
config/provider later), `max_iterations` (default 500, shared with subagents),
|
|
`enabled_toolsets`/`disabled_toolsets`, `quiet_mode`, `save_trajectories`, `platform`
|
|
(`"cli"`, `"telegram"`, ...), `session_id`, `skip_context_files`, `skip_memory`, `credential_pool`.
|
|
`chat(message) -> str` is the simple interface; `run_conversation(user_message, system_message=None,
|
|
conversation_history=None, task_id=None) -> dict` returns `final_response` + `messages`.
|
|
|
|
## Agent loop (`agent/conversation_loop.py` + `agent/turn_*.py`)
|
|
|
|
Entirely synchronous, with interrupt checks, budget tracking, and a one-turn grace call:
|
|
|
|
```python
|
|
while (api_call_count < self.max_iterations and self.iteration_budget.remaining > 0) \
|
|
or self._budget_grace_call:
|
|
if self._interrupt_requested: break
|
|
response = client.chat.completions.create(model=model, messages=messages, tools=tool_schemas)
|
|
if response.tool_calls:
|
|
for tc in response.tool_calls:
|
|
messages.append(tool_result_message(handle_function_call(tc.name, tc.args, task_id)))
|
|
api_call_count += 1
|
|
else:
|
|
return response.content
|
|
```
|
|
|
|
Each phase of an iteration is its own sibling, so a change to (say) overflow handling touches one
|
|
~600-line file: `turn_preflight*`, `turn_iteration_prep`, `turn_request_assembly`/`turn_api_request`,
|
|
`turn_api_call`, `turn_api_error`, `turn_response_intake`/`turn_response_check`,
|
|
`turn_empty_response`, `turn_tool_round`/`turn_tool_validation`, `turn_overflow`,
|
|
`turn_truncation`, `turn_context_compaction`, `turn_recovery`, `turn_retry_state`,
|
|
`turn_stop_gates`, `turn_liveness`, `turn_usage`, `turn_final_response`, `turn_finalizer`,
|
|
`turn_summary`. Find the phase with `grep -rn "def X" agent/turn_*.py`.
|
|
|
|
Messages use OpenAI format `{"role": "system|user|assistant|tool", ...}`; reasoning content is stored
|
|
in `assistant_msg["reasoning"]`.
|
|
|
|
**Agent-level tools** (`todo`, `memory`, ...) are intercepted by `agent/tool_executor.py` through the
|
|
`INLINE_TOOL_EXECUTORS` table in `agent/inline_tool_executors.py` before `handle_function_call()`.
|
|
Adding one: register in that table (no `if name == ...` chain); `tools/todo_tool.py` is the pattern.
|
|
|
|
## Message-flow invariants (every change is reviewed against these)
|
|
|
|
- **Prompt caching must not break.** Never alter past context, change toolsets, reload memories,
|
|
or rebuild the system prompt mid-conversation. The system prompt is byte-stable for the life of
|
|
a conversation; the ONLY context mutation is compression. Anything that must inject content
|
|
mid-conversation rides a **user message or tool result**, never the system prompt: skill slash
|
|
commands (`agent/skill_commands.py`) inject as a user message; subdirectory `AGENTS.md` hints
|
|
(`agent/subdirectory_hints.py`) append to the tool result (head+tail truncated past `_MAX_HINT_CHARS = 32_000`, with a warning).
|
|
- **Strict role alternation.** Never two same-role messages in a row; never a synthetic user
|
|
message injected mid-loop. The one exception is `/steer`, delivered as a standalone user row
|
|
after a tool result (`assistant(tool_calls) → tool → user` is legal on every provider path) —
|
|
never smeared onto the already-persisted tool row, which append-only persistence would leave
|
|
divergent from the live request. Cron deliveries live in their own session for this reason.
|
|
- **Context files** (`agent/prompt_builder.py`) load from the CWD only at startup and are capped
|
|
(`CONTEXT_FILE_MAX_CHARS` / dynamic cap from the context window / `context_file_max_chars`).
|
|
Never load an install-tree `AGENTS.md` as project context (PR #64611); subdirectory hints reject
|
|
paths outside the working dir so `~/.codex/AGENTS.md` / `~/.claude/CLAUDE.md` never mix in.
|
|
- **`_last_resolved_tool_names` is a process-global in `model_tools.py`.** `_run_single_child()`
|
|
in `tools/delegate_tool.py` saves/restores it around subagent execution; code reading it may see
|
|
a temporarily stale value during child runs.
|
|
|
|
## Compression (`agent/compression_facade.py`, `conversation_compression.py`, `turn_context_compaction.py`)
|
|
|
|
Two layers: gateway session hygiene (85% threshold) and the agent `ContextCompressor` (50%,
|
|
configurable; per-model overrides; failure cooldown after provider-proven overflow). The algorithm
|
|
prunes old tool results first (no LLM call), then picks boundaries, then generates a structured
|
|
summary with the `auxiliary` compression model. In-place compaction keeps a single stable session
|
|
id; native Responses/Codex compaction paths are provider-specific. Compression is the sanctioned
|
|
cache break — keep it the only one. Full detail:
|
|
`website/docs/developer-guide/context-compression-and-caching.md`.
|
|
|
|
## Model and provider resolution
|
|
|
|
- Runtime provider/model resolution and its precedence: `website/docs/developer-guide/provider-runtime.md`.
|
|
Provider profiles are plugins (`plugins/model-providers/<name>/`, see `plugins/AGENTS.md`);
|
|
`agent/model_metadata.py` holds context lengths and capabilities.
|
|
- **Auxiliary (side-LLM) work** — curator, vision, embedding, title generation, session_search,
|
|
compression — resolves through `agent/auxiliary_client.py::_resolve_auto_route`; each task can pin
|
|
its own `provider/model/base_url/reasoning_effort` under `auxiliary:` in config.yaml.
|
|
- Fallback models and credential pools are resolution-chain code: E2E them with real imports
|
|
against a temp `HERMES_HOME`, not mocks (root rubric).
|
|
|
|
## Memory, context engines, curator
|
|
|
|
`agent/memory_provider.py` (ABC) + `agent/memory_manager.py` (orchestrator) drive memory-provider
|
|
plugins; `agent/context_engine.py` drives context-engine plugins; `agent/image_gen_provider.py`
|
|
image-gen plugins (all in `plugins/AGENTS.md`). `agent/curator.py` + `curator_backup.py` implement
|
|
the skill curator (`skills/AGENTS.md`). Cron sessions pass `skip_memory=True` by default — memory
|
|
providers intentionally do not run during cron.
|
|
|
|
## Tests
|
|
|
|
Loop/phase tests go in `tests/agent/`; patch the binding the phase actually reads (siblings often
|
|
`from run_agent import X` inside the function — root "patch where production reads"). Assert
|
|
message-shape invariants (alternation, byte-stable system prompt) rather than snapshotting prompt
|
|
text.
|
|
|
|
Long-form: `website/docs/developer-guide/agent-loop.md`, `prompt-assembly.md`,
|
|
`context-compression-and-caching.md`, `provider-runtime.md`, `session-storage.md`,
|
|
`subagent-lifecycle-api.md`.
|