Code Editing Agent (CEA)
Relevant source files
The following files were used as context for generating this wiki page:
The Code Editing Agent (CEA) is the primary functional implementation of the plugsuits project, designed to act as an expert software engineer assistant. It provides a full-featured environment for autonomous and interactive coding tasks, leveraging the core Harness for logic and TUI or Headless modules for interaction.
CEA integrates model-agnostic agent loops with a specialized suite of tools for file manipulation, shell execution, and workspace exploration. It is specifically optimized for deterministic file editing using a "hashline" engine, which ensures stale-safe modifications by verifying file states before applying changes.
Sources: README.md:16-25, packages/cea/src/AGENTS.md:7-10, packages/cea/src/context/system-prompt.ts:36-38
System Architecture
The CEA architecture is built as a layered system within a monorepo structure. It sits at the top of the dependency chain, utilizing the @ai-sdk-tool/harness, @ai-sdk-tool/tui, and @ai-sdk-tool/headless packages to provide its services.
This diagram illustrates the internal structure of the CEA package and its dependency on core project modules.
Sources: AGENTS.md:12-25, packages/cea/src/AGENTS.md:12-26
Entrypoints and Runtimes
CEA supports two distinct runtimes to accommodate different operational needs:
Interactive CLI (TUI)
The interactive runtime uses the @ai-sdk-tool/tui package to provide a terminal-based user interface. It handles a lifecycle of run -> processInput -> processAgentResponse and supports slash commands for model switching and session management.
Sources: packages/cea/src/AGENTS.md:30, AGENTS.md:50
Headless Streaming
The headless runtime emits structured JSONL events (user, tool_call, tool_result, assistant, error) to stdout. This mode is designed for CI/CD integration, automation, and benchmarking.
Sources: packages/cea/src/AGENTS.md:31, README.md:65-69
| Feature | CLI (TUI) | Headless |
|---|---|---|
| Output Format | Interactive Terminal UI | Structured JSONL |
| User Input | Real-time keyboard input | Initial prompt argument |
| Continuation | User-driven | Auto-todo completion |
| Primary Use | Development / Debugging | CI/CD / Benchmarks |
Sources: packages/cea/src/AGENTS.md:30-32, README.md:60-70
Tools Subsystem
The tools subsystem is the "hands" of the CEA. It is categorized into functional groups managed through a central registry.
File Exploration and Search
CEA prioritizes dedicated exploration tools over generic shell commands for gathering context.
- read_file: Enforces safety limits and provides line anchors for future edits.
- grep_files: Efficient content searching across the workspace.
- glob_files: File discovery using pattern matching.
Deterministic File Modification
The "Hashline" engine is the core of CEA's file editing capability. It uses LINE#HASH anchors to ensure that edits are applied to the exact intended lines, even if the file has changed slightly.
- edit_file: Supports
replace,append, andprependoperations with mandatoryexpected_file_hashchecks. - write_file: Creates or completely overwrites files.
- delete_file: Removes files from the workspace.
Shell Execution
- shell_execute: Used for non-interactive tasks like
git,npm build, or running tests. - shell_interact: Allows for interactive shell sessions where required.
Sources: packages/cea/src/tools/AGENTS.md:7-18, packages/cea/src/context/system-prompt.ts:46-64, README.md:21-23
Workspace Management and Persistence
CEA maintains state and task tracking through a dedicated planning and persistence layer.
Todo System
The todo_write tool allows the agent to persist its current state and planned tasks. This is critical for the "Todo Continuation" middleware, which reminds the agent of incomplete tasks in autonomous loops.
This flow shows how CEA uses the TODO system to maintain state across multiple turns.
Sources: packages/harness/src/todo-continuation.ts, packages/cea/src/tools/planning/todo-write.ts:109-130
State Data Structure
The todo_write tool accepts a structured array of todo items:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the task |
content | string | Brief description of the task |
status | enum | pending, in_progress, completed, cancelled |
priority | enum | high, medium, low |
description | string | Optional detailed context |
Sources: packages/cea/src/tools/planning/todo-write.ts:19-30
Core Operational Principles
The CEA follows strict principles to ensure safety and efficiency during code editing:
- Understand Before Acting: The agent MUST use
read_fileorgrep_filesbefore attempting any edit. Assuming file contents is an anti-pattern. - Tool Specialization: Shell tools like
cat,sed, orawkare forbidden for file manipulation; CEA-specific tools must be used instead. - Parallel Execution: Independent tool calls (e.g., reading multiple files) should be executed in parallel within a single response to optimize performance.
- Path Preservation: CEA must maintain the exact path format (absolute vs. relative) provided in the initial task.
Sources: packages/cea/src/context/system-prompt.ts:41-86, packages/cea/src/tools/AGENTS.md:21-26
Summary
The Code Editing Agent (CEA) provides a robust framework for AI-driven software engineering within the plugsuits ecosystem. By combining deterministic file editing, structured task management, and flexible runtimes, it enables both interactive development and automated code maintenance with high reliability and safety.