TunaCode Agent Loop Ontology (Single Source of Truth)

TunaCode Agent Loop Ontology (Single Source of Truth)

Status: authoritative as implemented in code (not aspirational).

Scope: This document describes the current request/iteration loop and the node orchestrator (tool dispatch + tool returns + usage/thought recording) so the system can be replaced cleanly.

Source of truth: code only.

Primary code locations:

• Request loop (per user message): src/tunacode/core/agents/main.py
  • RequestOrchestrator (class)
  • process_request(...) (function)
• Node orchestrator (per streamed node): src/tunacode/core/agents/agent_components/orchestrator/orchestrator.py
  • process_node(...) (function)
• Tool dispatch pipeline:
  • dispatch_tools(...): src/tunacode/core/agents/agent_components/orchestrator/tool_dispatcher.py
  • collection/normalization: .../orchestrator/_tool_dispatcher_collection.py, .../_tool_dispatcher_registry.py
  • execution + retries: .../orchestrator/_tool_dispatcher_execution.py, src/tunacode/core/agents/agent_components/tool_executor.py
• Tool return handling: emit_tool_returns(...): .../orchestrator/tool_returns.py
• Streaming instrumentation: stream_model_request_node(...): src/tunacode/core/agents/agent_components/streaming.py
• State contracts:
  • StateManagerProtocol: src/tunacode/core/types/state.py
  • runtime structures: src/tunacode/core/types/state_structures.py
  • tool lifecycle registry: src/tunacode/core/types/tool_registry.py

0) Terminology (Ontology)

Concepts (nouns)

Request

• A single user message processed by process_request(...).

Run handle / AgentRun

• The object returned by pydantic_ai.Agent.iter(...) context manager.
• Treated as Any via tunacode.infrastructure.llm_types.AgentRun = Any.
• Must support at least:
  • async iteration yielding Nodes
  • .ctx (used for streaming)
  • .all_messages() (used for persistence)

Node

• One element yielded by async for node in run_handle:.
• Structural contract is defined by attributes accessed by TunaCode (see §4).

Session

• The mutable runtime state behind StateManagerProtocol.session.

Tool registry

• session.runtime.tool_registry: ToolCallRegistry
• The single source of truth for tool call lifecycle tracking.

ResponseState

• tunacode.core.agents.agent_components.response_state.ResponseState
• A state machine wrapper used for UI/flow tracking (USER_INPUT → ASSISTANT → TOOL_EXECUTION → RESPONSE).

Processes (verbs)

Request loop

• The outer orchestration of an agent run for a single user request.

Node orchestration

• The per-node processing step that:
  • consumes tool returns from the node request
  • records thought
  • updates usage
  • dispatches tool calls
  • transitions response state

1) Public Replacement Surface (what you must preserve)

If you want to replace the agent loop implementation/framework, you must preserve the observable behavior of these public surfaces:

1.1 process_request(...)

Location: src/tunacode/core/agents/main.py

async def process_request(
    message: str,
    model: ModelName,
    state_manager: StateManagerProtocol,
    tool_callback: ToolCallback | None = None,
    streaming_callback: StreamingCallback | None = None,
    tool_result_callback: ToolResultCallback | None = None,
    tool_start_callback: ToolStartCallback | None = None,
    notice_callback: NoticeCallback | None = None,
) -> AgentRun:
    ...

Input contract

• message: str
  • user’s prompt for this request.
• model: ModelName (ModelName = str)
  • model selector string consumed by get_or_create_agent(...) (see §2.2).
• state_manager: StateManagerProtocol
  • must provide .session containing at least the fields referenced in §3.
• callbacks (optional)
  • tool_callback: invoked for each tool call batch item (see §5.3)
  • streaming_callback: invoked with streaming text deltas (see §5.1)
  • tool_start_callback: called once per dispatched batch (best-effort UI signal)
  • tool_result_callback: called once per tool return observed in the next request
  • notice_callback: called when empty-response intervention triggers

Output contract

• Returns an AgentRun (framework object) wrapped with .response_state:
  • actual returned type is tunacode.core.agents.agent_components.result_wrapper.AgentRunWithState
  • it delegates all attributes to the underlying run handle and adds:

run.response_state  # ResponseState

Side effects (authoritative)

• Mutates state_manager.session.* (details in §3)
• Updates session.conversation.messages to the run’s authoritative messages at end of run
• Updates session.conversation.thoughts
• Updates session.usage.last_call_usage and accumulates totals
• Updates session.runtime.tool_registry during tool call/return lifecycle

Exceptions

• May raise (non-exhaustive):
  • GlobalRequestTimeoutError (if global timeout enabled)
  • UserAbortError (propagated)
  • asyncio.CancelledError (propagated)
  • framework/network/tool exceptions not caught by outer loop

1.2 Node orchestration entry point: process_node(...)

Location: src/tunacode/core/agents/agent_components/orchestrator/orchestrator.py

async def process_node(
    node: Any,
    tool_callback: ToolCallback | None,
    state_manager: StateManagerProtocol,
    _streaming_callback: StreamingCallback | None = None,
    response_state: ResponseState | None = None,
    tool_result_callback: ToolResultCallback | None = None,
    tool_start_callback: ToolStartCallback | None = None,
) -> tuple[bool, str | None]:
    ...

Output contract

• Returns (is_empty: bool, reason: str | None).
  • is_empty=True means the model response had no non-empty text and no structured tool calls.
  • reason is currently either "empty" or None.

2) Execution Model (what happens)

2.1 UI → core loop

Typical caller: src/tunacode/ui/app.py calls process_request(...) inside an asyncio.Task.

The agent loop is designed so UI can:

• render tool start events (tool_start_callback)
• render tool results as they come back (tool_result_callback)
• (optionally) stream deltas (streaming_callback)—currently passed as None by the Textual UI.

2.2 Agent creation + caching

Location: src/tunacode/core/agents/agent_components/agent_config.py

• get_or_create_agent(model, state_manager) is the only constructor path.
• Caches agents in:
  • session cache: session.agents[model] and session.agent_versions[model]
  • module cache: tunacode.infrastructure.cache.caches.agents
• Agent version hash is computed from:
  • settings.max_retries
  • settings.tool_strict_validation
  • request delay
  • settings.global_request_timeout

System prompt composition (as implemented):

1. load src/tunacode/prompts/system_prompt.md
2. append a context file from CWD (default: AGENTS.md) via load_tunacode_context()

2.3 Message history preparation

Location: src/tunacode/core/agents/history_preparer.py

Before calling into the framework, the loop:

• prunes old tool outputs for token budget (prune_old_tool_outputs)
• runs cleanup loop to remove inconsistencies (run_cleanup_loop)
• drops a trailing "request" message to avoid consecutive requests
• sanitizes history for resume (sanitize_history_for_resume)

Output:

• message_history: list[Any] passed to agent.iter(..., message_history=...)
• baseline_message_count: int used later to preserve messages externally appended during run

2.4 Outer request loop (per request)

Location: src/tunacode/core/agents/main.py

Control flow:

1. RequestOrchestrator.run()
   • applies global timeout (if enabled via session config)
2. _run_impl()
   • initializes request context + resets per-run fields
   • gets or creates an agent
   • prepares history
   • enters framework iteration context: async with agent.iter(...) as run_handle:
3. _run_agent_iterations(...)
   • iterates nodes with async for node in run_handle:
   • for each node calls _handle_iteration_node(...)
4. on completion:
   • persists run messages into session.conversation.messages

Important: max_iterations is currently NOT enforced.

• RequestContext.max_iterations is computed and stored but never checked in the loop.

2.5 Per-node iteration

Location: src/tunacode/core/agents/main.py (_handle_iteration_node)

Per node:

1. update runtime counters:
   • runtime.current_iteration = iteration_index
   • runtime.iteration_count = iteration_index
2. optional streaming:
   • if streaming_callback and Agent.is_model_request_node(node) then stream_model_request_node(...)
3. node orchestration:
   • calls process_node(...)
4. empty response handling:
   • if empty, triggers handle_empty_response(...) and notice_callback(...)
5. completion:
   • stops early only if response_state.task_completed is set True

3) State & Side-Effects Contract (StateManager / Session)

This section is essential for replacement: the loop is not pure; it encodes state mutations that callers (UI) rely on.

3.1 Fields reset per request

Location: RequestOrchestrator._reset_session_state()

Mutations:

• runtime.current_iteration = 0
• runtime.iteration_count = 0
• runtime.tool_registry.clear()
• runtime.batch_counter = 0
• runtime.consecutive_empty_responses = 0
• session.task.original_query = "" then immediately set to message (see below)

3.2 Request identity

• runtime.request_id is set to the first 8 chars of a UUID4.

3.3 Original query

• Intended to be set once, but as implemented it is effectively set every request:
  • _reset_session_state() clears it
  • _set_original_query_once() then sets it to the request message

3.4 Conversation persistence rules

Location: RequestOrchestrator._persist_run_messages(...)

At run end:

• run_messages = list(run_handle.all_messages())
• external_messages = conversation.messages[baseline_message_count:]
• conversation.messages = run_messages + external_messages

Meaning:

• the run handle is the authoritative source for messages during the run
• any messages appended externally during the run after baseline are preserved

3.5 Tool registry lifecycle

Location: core/types/tool_registry.py + tool dispatcher + tool returns

Observed lifecycle:

1. tool call discovered → tool_registry.register(tool_call_id, tool_name, args)
2. about to execute → tool_registry.start(tool_call_id)
3. later tool return observed in a subsequent model request → tool_registry.complete(tool_call_id, result)
4. on execution failure → tool_registry.fail(tool_call_id, error)
5. on user abort during execution → tool_registry.cancel(tool_call_id, reason)

Invariant:

• Tool return consumption relies on the args being registered by tool_call_id.
  • tool returns call consume_tool_call_args(...)
  • it raises if args are missing.

3.6 Usage tracking

Location: .../orchestrator/usage_tracker.py

• On each node with model_response, usage is normalized and:
  • session.usage.last_call_usage = UsageMetrics(...)
  • session.usage.session_total_usage.add(last_call_usage)

3.7 Streaming debug state

Location: .../agent_components/streaming.py

On stream start:

• session._debug_raw_stream_accum reset to ""
• session._debug_events reset to []

Streaming callback is invoked with text deltas; deltas are appended to _debug_raw_stream_accum.

4) Structural Contracts (framework objects treated as Any)

Because pydantic_ai types are mostly typed as Any in tunacode.infrastructure.llm_types, TunaCode relies on structural typing.

4.1 Node: minimum attributes used by TunaCode

A node is any object with some/all of:

• node.request: Any | None
  • when present, request.parts is iterated for tool-return parts
• node.model_response: Any | None
  • when present, model_response.parts: list[Any] is read
  • model_response.usage is passed to usage normalization
• node.thought: str | None
  • when present, appended to session.conversation.thoughts
• node.result: Any | None
  • when present, node.result.output is read to detect user-visible output

Optional streaming capability:

• node.stream(agent_run_ctx) must be an async context manager that yields an async iterator of events.

4.2 Message parts: minimum attributes used

For response parts (model_response.parts) and request parts (request.parts):

• part.part_kind: str
  • tool calls: "tool-call"
  • tool returns: "tool-return"
  • text: "text"
• part.content: Any (text/tool return content)
• Tool call specific:
  • part.tool_call_id: str | None
  • part.tool_name: str | None
  • part.args: str | dict | None

5) Callback Contracts (inputs/outputs/failure behavior)

5.1 StreamingCallback

Type: Callable[[str], Awaitable[None]]

Contract:

• Called with ordered text deltas.
• If it raises, the streaming path raises and the request fails.

5.2 ToolResultCallback

Type: Callable[[ToolName, str, ToolArgs, str | None, float | None], None]

Called when:

• tool-return parts are observed in node.request.parts.

Arguments:

• tool_name: tool name from tool-return part (string)
• status: always "completed" in current emitter
• args: resolved from tool registry by tool_call_id
• result: stringified tool return content
• duration_ms: always None in current emitter

Failure behavior:

• Exceptions propagate (no try/except around callback).

5.3 ToolCallback (tool execution hook)

Type: Callable[[ToolCallPartProtocol, StreamResultProtocol], Awaitable[None]]

Where called:

• dispatch_tools(...) collects tool call parts and then executes them through execute_tools_parallel(...), which calls the callback once per tool call.

Semantics:

• The callback is the “executor” for the tool call part in the context of the current node.
• If it raises:
  • retry logic may retry unless the exception is non-retryable (see NON_RETRYABLE_ERRORS in tool_executor.py).
  • ultimate failure is recorded in the tool registry (fail(...) or cancel(...)).

5.4 ToolStartCallback

Type: Callable[[str], None]

Called when:

• a batch of tool calls is about to execute.

Argument:

• a display string of up to N tool names, with a suffix if truncated.

5.5 NoticeCallback

Type: Callable[[str], None]

Called when:

• an iteration response is detected as empty.

Argument:

• a generated user-facing notice string.

6) Abort / Timeout / Cleanup Semantics

6.1 Global request timeout

Location: RequestOrchestrator.run()

• timeout is computed via _coerce_global_request_timeout(session).
• when triggered:
  • agent cache is invalidated (invalidate_agent_cache(model, state_manager))
  • raises GlobalRequestTimeoutError(timeout)

6.2 Abort / cancellation cleanup

Location: RequestOrchestrator._handle_abort_cleanup()

If UserAbortError or asyncio.CancelledError bubbles up:

1. If session._debug_raw_stream_accum has partial streamed text, append a synthetic interrupted ModelResponse to conversation history.
2. Sanitize message history:
   • remove dangling tool calls
   • remove empty responses
   • remove consecutive requests
3. Invalidate the agent cache for the model.

7) Replaceability Checklist (what a new engine must provide)

To replace the current implementation cleanly, implement an adapter that provides the same structural contracts and side effects:

7.1 Engine must support

• async context manager “run handle”
• async iteration over “nodes”
• per node:
  • tool return parts reachable at node.request.parts
  • response parts reachable at node.model_response.parts
  • optional thought string
  • optional final output at node.result.output
• run handle must provide all_messages() to persist history

7.2 Tool loop integration must preserve

• tool call discovery (structured + fallback from text)
• tool registry registration/args normalization keyed by tool_call_id
• tool return consumption using tool_call_id → args mapping

7.3 State updates must preserve

• session runtime counters and request_id
• conversation messages persistence strategy (authoritative run messages + preserve external appends)
• usage metrics updates

8) Index of Relevant Files (for code navigation)

• src/tunacode/core/agents/main.py
  • RequestOrchestrator
  • EmptyResponseHandler
  • _handle_iteration_node
• src/tunacode/core/agents/history_preparer.py
• src/tunacode/core/agents/agent_components/agent_config.py
• src/tunacode/core/agents/agent_components/streaming.py
• src/tunacode/core/agents/agent_components/orchestrator/orchestrator.py
• src/tunacode/core/agents/agent_components/orchestrator/tool_dispatcher.py
• src/tunacode/core/agents/agent_components/orchestrator/tool_returns.py
• src/tunacode/core/agents/agent_components/tool_executor.py
• src/tunacode/core/types/state.py
• src/tunacode/core/types/state_structures.py
• src/tunacode/core/types/tool_registry.py