ENT AGENT

ent-agent is a simple harness which attaches an underlying agent framework with entomologist, allowing an agent to operate on a repository which is using entomologist.

FEATURES

1. utilizes entomologist for agent control
2. customizable + portable agent identity
3. swappable underlying agent
4. direct attach to git repository
5. uses git branches with human-in-the-loop review

STRUCTURE

the harness has a simple dual-loop structure, which maximizes determinism in the control flow.

CONFIGURATION

information needed:

1. ssh keypair
2. git url
3. agent name / email to be used in git commits + ent

configuration is provided by the config.toml file with the following entries:

• ssh_key_dir
• repo_url
• agent_name
• agent_email
• agent_type
• agent_config_dir

OUTER LOOP (DETERMINISTIC)

FIRST RUN

on the first run, the outer loop checks the identity directory for an ssh keypair - if no keypair is found, a new keypair will be generated, and the outer loop attemps to fetch the git repository (or clone if it does not exist). if the git operation fails, the outer loop logs an error and sleeps for one minute before trying again.

GENERAL

the outer loop first syncs the repository with git fetch.

the outer loop selects entomologist tasks assigned to the agent, which are in any of the following states, in the following priority order:

1. blocked
2. inprogress
3. backlog
4. new

tasks are worked on in a new branch named after the issue ID with the following format: <AGENT ID>/<ISSUE ID>

if the branch does not already exist, the outer loop will create the new branch, and check it out in a worktree directory.

the outer loop then hands off the selected task to the inner loop, which is started inside the worktree directory.

after the inner loop has completed, the outer loop syncs the entomologist-data branch with the origin, and ensures the inner loop's branch has been pushed.

INNER LOOP (NON-DETERMINISTIC)

the outer loop launches the inner-loop task inside the worktree directory. here, the non-deterministic agent operations run, using whatever framework is selected.

for the first implementation, this repository will use the hermes agent.

the inner agent is allowed to operate on the attached repository, using the worktree directory which it is running from.

as the agent works, it will add comments to the entomologist issue as needed, and will continue working until the following:

1. agent's work has been completed

• agent comments on the work that has been done
• agent commits changes to the branch
• agent moves the task state to blocked and assigns the task to reviewer (reviewer may be the issue author unless stated otherwise in the issue description)

2. agent is stuck (i.e. can not solve the problem without external assistance incl. decision-making, external resources, etc.)

• agent comments what assistance is required / what problem was encountered
• agent commits any changes that should be saved to the branch as a WIP commit
• agent moves the task state to blocked and assigns the task to handler (handler defaults to the issue author unless overridden in the issue description)

in all cases, at the end of each agent's run, it should ensure that the worktree is in a clean state, with no untracked files (either delete or commit them).