Deconstructing the Runtime Architecture and Log Trajectory of AI Coding Agents

    This article examines the architectural design of an open runtime for AI coding agents, clarifying its role as an extensible infrastructure rather than a finished product. It breaks down the six-layer architecture, the unified session model across multiple entry points, the session event log and trajectory projection mechanism, and the coordination among permissions, sandboxing, and the agent loop. The discussion is intended for both end users evaluating readiness and platform developers building custom agent experiences, with emphasis on observability, modularity, and controlled execution.

    1. Clarifying the Positioning: An Open Runtime, Not a Finished Application

    As AI coding tools evolve rapidly, the term “runtime” is often mistaken for a turnkey coding assistant. Taking a publicly available coding agent runtime as an example, its true purpose is not to be an out-of-the-box end-user product, but rather an open infrastructure on which agents can be further constructed. It serves a dual identity:

    • On one hand, it can host browser interfaces, headless command-line tools, language-level SDKs, and other entry points, forming a usable coding agent experience.
    • On the other hand, it decomposes the model provider layer, tool set, session management, permission policies, sandbox execution, agent loop, and UI layer into composable modules for platform developers to extend.

    This dual identity implies an asymmetric maturity. The runtime layer is generally more mature in its openness—module boundaries are clear, configuration can be replaced, session logs are observable, and execution trajectories can be projected. Meanwhile, the default product experience is often still in developer preview, with room for improvement in desktop experience, cross-platform compatibility, daily coding efficiency, and default interaction details compared to common commercial terminal solutions. Therefore, evaluating such a runtime should not simply apply a “rankings of finished tools” perspective, but should distinguish two types of audiences:

    • End users care about: mature coding agent experience, desktop applications, terminal interaction, cross-platform compatibility, cache hit rates, everyday coding productivity, and the upper bound of benefit that the runtime can provide for different model sizes.
    • Platform developers care about: plugin systems, preset combinations, trajectory observability, runtime self-modification capabilities, permission and sandbox boundaries, and multi-entry coordination.

    Both sets of requirements are legitimate, but they correspond to different levels of architectural capability. Understanding this is a prerequisite for deconstructing the entire runtime system.

    2. Overall Architecture: Layered Decoupling and Recomposability

    From an architectural perspective, this type of runtime can be divided into six layers. Each layer communicates through stable contracts, avoiding tight coupling among the model, tools, UI, and storage.

    1. Entry Layer: Provides multiple usage paths, such as browser UI, headless CLI, language-level SDK, and package manager entry. The entry layer only handles parameter parsing, session creation, and event forwarding; it does not carry agent logic directly.
    2. Configuration and Preset Layer: Handles default configuration, model providers, tool allowlists, permission policies, sandbox parameters, and UI options. Presets are composable for switching between different task types.
    3. Runtime Core Layer: Includes the agent loop, context assembly, tool call scheduling, session state machine, and error recovery strategies. This layer is the primary enforcer of the constraint that “any content visible to the model must already be persisted to the log.”
    4. Execution and Security Layer: Covers sandbox execution, filesystem boundaries, network access policies, approval mechanisms, and tool permission validation. Default policies should be conservative, with presets opening up capabilities item by item.
    5. Observability Layer: Based on session event logs, provides trajectory projection, runtime information panels, cache hit rates, I/O tokens, and token rate metrics.
    6. UI Layer: Can be a browser interface, terminal interface, or IDE sidebar. It only consumes read-only data exposed by the observability layer and the runtime core layer, and must not bypass logs to “add extra instrumentation.”

    The key value of this layered design is decoupling and recomposability: the model provider layer can be swapped, the tool set can be trimmed, session management can be persisted independently, permission policies can be overridden per project, sandbox execution can be switched based on risk levels, the agent loop can be configured per task type, and the UI layer can evolve independently. For platform developers, this means the runtime behaves more like an “agent operating system” than a closed application.

    A simplified pseudo-configuration illustrates this composability:

    1. runtime:
    2. entrypoints:
    3. - browser_ui
    4. - headless_cli
    5. - python_sdk
    6. - package_manager
    7. provider:
    8. model: "replaceable model"
    9. context_window: "declared per model"
    10. session_log:
    11. format: jsonl
    12. compression: high
    13. append_only: true
    14. permissions:
    15. default_deny: true
    16. tool_allowlist: []
    17. sandbox:
    18. filesystem: workspace_only
    19. network: deny_by_default
    20. agent_loop:
    21. max_turns: "configured per task"
    22. recovery: "log failures and retry"
    23. observability:
    24. trace_panel: true
    25. metrics:
    26. - cache_hit
    27. - io_tokens
    28. - token_rate

    This configuration does not point to a specific product interface; it simply demonstrates how layers of the runtime combine through declarative configuration. Real engineering practice should be validated against public documentation and actual code repositories, avoiding the mistake of treating illustrative fields as fixed interfaces.

    3. Multi-Entry Deployment: A Unified Session Model Is Central

    In local deployment, the four entry points are often validated separately: browser UI suits interactive coding and result preview; headless CLI suits scripting, batch processing, and continuous integration; language-level SDK suits embedding into custom platforms; package manager entry suits quick installation and version pinning. Despite different entry methods, the underlying system should share the same session model and event log format; otherwise trajectories cannot be correlated and permission policies tend to diverge.

    In practice, a unified session model must satisfy three requirements. First, the entry layer only creates sessions and forwards events; it does not maintain a “shadow state” of its own. Second, all model-visible context, tool call requests, tool results, approval decisions, and error messages must be written to the session event log before moving to the next loop iteration. Third, the UI layer only reads the log projection and does not modify runtime state. This way, when the same task is initiated from the browser and resumed from the headless CLI, the trajectory remains consistent.

    Default configuration decomposition should also revolve around these three points. The model provider determines the context window and call parameters; the tool set defines the scope of available capabilities; the session log defines recoverability and auditability; permissions and sandbox define the risk ceiling; the agent loop determines how the task progresses; and the UI layer determines how observability information is presented. The default configuration should not aim for “all capabilities enabled” but rather prioritize traceability, recoverability, and restrictability.

    4. Session Event Logs and Trajectory Projection Mechanism

    The most notable design constraint in this type of runtime is: anything visible to the model must already be persisted to the log. This means the trajectory is not an independently instrumented monitoring layer; it is a read-only projection derived from the session event log. Logs are typically stored in append-only, compressed JSONL format, recording events such as session creation, context assembly, model requests, tool calls, tool results, permission approvals, sandbox output, and loop termination.

    Treating the trajectory as the “developer tools for agents” is an appropriate analogy. The runtime information panel can expose cache hits, I/O tokens, and token rates in real time, helping developers determine whether the context is bloated, whether tool returns are too large, whether the cache is effective, and whether the loop is stuck in repetitive calls. But the panel itself should not become a second data source; otherwise, if panel instrumentation falls out of sync with the log, debugging loses a trustworthy baseline.

    A simplified pseudo-code for a read-only projection:

    1. def project_trajectory(session_log_path):
    2. events = read_jsonl(session_log_path) # append-only log
    3. trace = []
    4. for event in events:
    5. if event.type in {
    6. "model_request",
    7. "tool_call",
    8. "tool_result",
    9. "permission_decision",
    10. "sandbox_output",
    11. "loop_end",
    12. }:
    13. trace.append({
    14. "turn": event.turn,
    15. "type": event.type,
    16. "summary": event.summary,
    17. "tokens": event.get("tokens"),
    18. "cache_hit": event.get("cache_hit"),
    19. })
    20. return trace # read-only projection, does not modify the original log

    This design brings three benefits:

    • Recoverability: After a session interruption, the context can be rebuilt from the log.
    • Auditability: Permission decisions and tool calls are traceable.
    • Comparability: When the same model is connected to different runtimes, event sequences can be compared for tool call density, error recovery paths, and token consumption patterns.

    Note that log compression and append-only writes introduce storage and read costs; engineering practices should include retention policies, redaction rules, and access control.

    5. Coordination of Permissions, Sandbox, and Agent Loop

    Permissions and sandboxing are not auxiliary features; they are part of the agent loop. Default-deny policies, tool allowlists, workspace-only filesystem isolation, deny-by-default network access, and approval for high-risk operations all alter how the loop progresses. For example, when a tool call is rejected by a permission policy, the runtime should not simply terminate. It should write the rejection reason to the log and allow the model to select a lower-risk alternative path in the next iteration.

    The agent loop layer must handle four state categories: normal tool calls, permission denials, sandbox failures, and abnormal model output. Each state must produce a projectable event to avoid “silent failures.” Platform developers extending plugins or presets should also adhere to this constraint: any new tool must declare its permission requirements, sandbox requirements, and log fields; otherwise the observability of the trajectory is broken.

    6. Comparative Experiments and Complex Task Practice

    A reasonable approach to evaluating such a runtime is to fix the model, task, and environment, then connect the open runtime and a mature commercial solution separately, comparing their execution trajectories. Metrics to observe include: number and order of tool calls, number of permission approvals, cache hit changes, I/O token proportion, error recovery turns, and completeness of the final artifact. Such comparisons are only meant to observe differences in capabilities and thresholds; they should not be used as a product ranking, nor should data from a single local run be extrapolated into universal conclusions.

    In a complex full-stack task, one can design a chain involving a frontend page, backend API, data validation, and visual output. The runtime must first decompose requirements, then generate code, run builds, read error logs, fix issues, and finally output a previewable visual result. The practical focus is to retain the complete session event log so the trajectory can explain why a particular tool was called, why a retry occurred, and why the final product passed validation. For tasks with visual output, screenshots or rendered results should be recorded as event attachments, while the attachments themselves must be redacted and subject to retention policies.

    7. Conclusion

    Overall, the architectural value of this type of coding agent runtime lies in its openness and recomposability: multiple entry points share a unified session model, configuration and presets are composable, permissions and sandbox can be constrained, session event logs support read-only trajectory projection, and the agent loop is decoupled from the UI layer. What is currently more mature is the runtime infrastructure, not the default finished product experience. Both end-user and platform-developer expectations are valid, but evaluation should distinguish the levels: the former focuses on daily coding productivity and interaction completeness, while the latter focuses on plugin systems, preset combinations, trajectory observability, and runtime extensibility. Only through comparative practice under the unified log constraint can one accurately determine capability boundaries and applicable scenarios.