Core Layer

Core Layer

Package: src/tunacode/core/

What

The engine. Takes a user message, routes it through a tinyagent Agent, handles streaming events, manages compaction, tracks tool calls, and persists session state.

Sub-Packages

agents/ -- Agent Loop

compaction/ -- Context Window Management

session/ -- State Persistence

logging/ -- Structured Logging

types/ -- Core Protocols

Other

How

Request Lifecycle

User types message
    |
    v
TextualReplApp._process_request(message)
    |
    v
process_request(message, model, state_manager, callbacks...)
    |
    v
RequestOrchestrator.run()
    |-- _initialize_request()      reset counters, generate request_id
    |-- get_or_create_agent()      build/cache tinyagent Agent
    |-- _coerce_tinyagent_history() validate session messages are dicts
    |-- _compact_history_for_request() threshold check + summarize if needed
    |-- agent.replace_messages()    load compacted history into agent
    |-- _run_stream(agent, ...)     main event loop
    |       |
    |       |  async for event in agent.stream(message):
    |       |    message_update  -> streaming_callback (UI delta)
    |       |    message_end     -> parse usage, update session totals
    |       |    tool_execution_start -> register tool, notify UI
    |       |    tool_execution_end   -> mark complete/failed, notify UI
    |       |    turn_end        -> increment iteration, enforce max
    |       |    agent_end       -> persist messages to session
    |       |
    |-- _retry_after_context_overflow_if_needed()
    |       force-compact and retry once if API returns context_length_exceeded
    |
    v
Return to UI for rendering

Compaction Flow

CompactionController.check_and_compact(messages, max_tokens)
    |-- should_compact?  estimate_tokens vs (max_tokens - reserve - keep_recent)
    |       no  -> return skip outcome
    |       yes -> ContextSummarizer
    |                  |-- calculate_retention_boundary (walk backward, find safe split)
    |                  |-- serialize_messages (to text transcript)
    |                  |-- _summary_generator (call LLM with summarize prompt)
    |                  |-- return summary string
    |-- update CompactionRecord on session
    |-- return CompactionOutcome(status=compacted, messages=retained)

Session Persistence

StateManager.save_session() serializes to JSON:

• Messages (must be tinyagent dicts; non-dict = hard error)
• Compaction record
• Usage totals
• Model, project_id, timestamps

StateManager.load_session() deserializes and separates thought entries from message history.

System Prompt

The system prompt defines TunaCode's identity and operational rules for the tinyagent framework.

Location: src/tunacode/prompts/system_prompt.md

Loading mechanism: load_system_prompt() in agent_config.py reads the markdown file at runtime and appends dynamic context from load_tunacode_context().

Dynamic context: load_tunacode_context() loads the user's AGENTS.md guide file (cached) and injects it into the prompt under the <user_context> section.

Tool philosophy: Tools are described by purpose and intent, not by function signature. The tinyagent framework provides JSON schemas separately. This keeps the prompt focused on when and why to use each tool:

Agent version hashing: _compute_agent_version() generates a cache key from configuration that affects agent behavior: max_retries, tool_strict_validation, request_delay, global_request_timeout, max_tokens.

Why

The RequestOrchestrator class exists to keep the streaming event loop testable and the callback wiring explicit. Each event type has its own handler method -- no giant switch statement.

Compaction is request-scoped (one compaction per request at most) to avoid compacting the same history repeatedly when the model makes multiple turns.

The StateManagerProtocol breaks the circular dependency between session state and agent creation -- agents need state, state stores agents.

tinyagent provides the agent framework (migrated from pydantic-ai), handling the underlying event streaming, tool schema generation, and message protocol conversion.