MainAgent

An application can integrate AchillesAgentLib through MainAgent, the package entry point for workspace skill discovery and conversational execution. The application creates one instance, then calls executePrompt() for a reusable conversation or executeSkill() for direct named-skill execution.

Request execution

The first executePrompt() call builds tools from enabled top-level skills and asks LLMAgent to create a LoopAgentSession. MainAgent stores that session in _session. Later calls use newPrompt(), preserving conversation history while allowing explicit model, tags, reasoning effort, and abort signal values for the new turn.

flowchart TB
      U[Application calls executePrompt] --> M[MainAgent discovers enabled tools and owns the reusable session]
      M --> S[LoopAgentSession plans, invokes tools, and keeps conversation state]
      S --> L[LLMAgent resolves the model and invokes the configured provider]
      L --> S
      S --> R[MainAgent returns result and session status]
      classDef caller fill:#eef4ff,stroke:#1c4f9c,color:#0f2557;
      classDef runtime fill:#f5f1ff,stroke:#6657b8,color:#2d246b;
      classDef provider fill:#eefbf4,stroke:#28875d,color:#174c38;
      class U,R caller; class M,S runtime; class L provider;

MainAgent request execution flow

initialHistory may hydrate only a newly created session. MainAgent rejects non-empty initial history after the reusable session exists, preventing duplicate history injection. cancelCurrentSession() forwards cancellation to both the session and LLMAgent.

Security supervision

MainAgent creates a default SecuritySupervisor unless the application supplies another supervisor through the constructor. For each new executePrompt() session, MainAgent passes the effective supervisor to LLMAgent.startLoopAgentSession(), which stores it on the LoopAgentSession.

Before a controlled tool runs, the session asks the supervisor whether execution is approved, denied, or approved persistently for the same operation. The supervisor therefore controls permission decisions at the tool boundary; it does not select tools, call the model, or execute skill code. When a session invokes a skill tool, MainAgent also forwards the parent session's supervisor in the execution options so nested skill or orchestration work can preserve the same approval authority.

Stage	Supervisor role
MainAgent construction	Uses the application-supplied supervisor or creates `SecuritySupervisor`.
Session creation	Passes the effective supervisor into the new LoopAgentSession.
Tool execution	The session requests an approval decision before invoking a controlled tool.
Nested skill execution	MainAgent forwards the parent session supervisor and any approval metadata to the delegated skill.

Primary methods

Method	Responsibility
`executePrompt(message, options)`	Creates or reuses the Loop session and returns its latest result and status.
`executeSkill(name, prompt, options)`	Resolves an enabled skill and delegates execution to its specialized subsystem.
`buildSkills()`	Runs enabled skills' asynchronous build hooks in parallel and isolates failures per skill.
`refreshSkills()`	Rediscovers workspace skills, reports additions, updates, and removals, and refreshes tools in the active session.
`enableSkills()` / `disableSkills()`	Validates a complete name batch before changing enabled state and refreshing the visible tool surface.
`getSkills()` / `getSkillRecord()`	Expose the canonical catalog and alias-based lookup.
`cancelCurrentSession()`	Interrupts the active session and in-flight model requests.
`shutdown()`	Cancels work, closes subsystems, clears the session, and closes the logger.

Skill discovery and boundaries

MainAgent searches below startDir and explicitly supplied additionalWorkspaceRoots for supported descriptors. Additional roots may be an array of directory paths or a synchronous resolver returning that array. The resolver runs at startup and on each refreshSkills(), allowing the caller to revalidate managed storage before discovery. Overlapping roots are deduplicated by descriptor path. Refresh removes stale records and aliases, preserves disabled-state intent, and leaves the existing catalog intact if root resolution fails. Discovery roots do not change startDir or the application's project and sandbox boundaries. Package-internal skills are excluded by default and become available when disableInternalSkills is false. User skills are registered after internal skills, so a matching canonical user skill replaces the internal record. Disabled skills are excluded from direct execution, builds, and session tools.

Subsystems own descriptor parsing, preparation, builds, and execution. MainAgent owns catalog state and routing; LLMAgent owns model interaction; the session owns conversational memory and step control.